Saltar al contenido
Notificado
Menú
Crear cuenta

API para afiliados

La API de la cuenta de afiliado en /v1/afiliados: el token, los alcances, las lecturas y la factura que espera su confirmación.

Actualizado:

La API de afiliados está en https://www.notificado.co/v1/afiliados. Sirve a un programa suyo (una hoja de cálculo, un script de su contador) lo mismo que el MCP para afiliados sirve a un asistente: su propia cuenta del programa de referidos, y nada más.

Es una API aparte de la de las firmas (/v1): un token de firma no alcanza nada bajo /v1/afiliados, y un token de afiliado no alcanza nada de una firma.

El token

Se crea en /afiliados, sección Acceso para agentes (MCP y API), con un nombre y sus alcances; se muestra una sola vez. El mismo token sirve para el MCP y para esta API. Cada llamada lo lleva en el encabezado Authorization:

curl 'https://www.notificado.co/v1/afiliados/my-affiliate-summary' \
  -H "authorization: Bearer $NOTIFICADO_AFFILIATE_TOKEN"
const response = await fetch('https://www.notificado.co/v1/afiliados/my-affiliate-summary', {
  headers: { authorization: `Bearer ${process.env.NOTIFICADO_AFFILIATE_TOKEN}` },
});

Ninguna operación pide un identificador de afiliado: el token dice quién es usted, y cada respuesta es de su cuenta.

Respuesta Cuándo
401 + WWW-Authenticate: Bearer Sin token, o con uno desconocido, vencido o revocado.
404 X_ROUTE_NOT_FOUND La operación está fuera de los alcances del token: responde igual que si no existiera.
403 X_FORBIDDEN El alcance la cubre, pero su cuenta no puede hacerla (por ejemplo, la afiliación está suspendida).
429 X_RATE_LIMITED Demasiadas solicitudes: espere los segundos de Retry-After y repita.

Alcances

Alcance Operaciones
affiliate:read El resumen (código, enlace de referido, embudo y saldos), el estado de la verificación, los estados de cuenta, el libro de movimientos y la descarga del documento soporte. Cada descarga queda registrada.
affiliate:invoices Subir los dos archivos de la factura electrónica de un estado de cuenta y presentarla, para que usted la confirme.
Operación Método y ruta Alcance
Resumen de la cuenta GET /v1/afiliados/my-affiliate-summary affiliate:read
Estados de cuenta GET /v1/afiliados/my-affiliate-statements affiliate:read
Libro de movimientos GET /v1/afiliados/my-affiliate-ledger affiliate:read
Descargar el documento soporte POST /v1/afiliados/download-affiliate-support-document affiliate:read
Autorizar la carga de un archivo POST /v1/afiliados/request-affiliate-invoice-upload affiliate:invoices
Confirmar la carga POST /v1/afiliados/confirm-affiliate-invoice-upload affiliate:invoices
Presentar la factura POST /v1/afiliados/submit-affiliate-invoice affiliate:invoices
Facturas que esperan su confirmación GET /v1/afiliados/my-pending-affiliate-invoices affiliate:invoices

Los listados se paginan como en la API de las firmas: _first=<filas> y la página siguiente con _after=<nextCursor>. La lista completa, con parámetros, respuestas y ejemplos, está en la referencia: Afiliados. El documento OpenAPI de esta API se descarga en https://www.notificado.co/v1/afiliados/openapi.json.

Presentar una factura

Una factura electrónica se presenta en tres pasos, igual que una carga en el panel:

  1. Pida una autorización de carga por cada archivo (request-affiliate-invoice-upload, con kind einvoice_xml o einvoice_pdf).
  2. Suba los bytes con un PUT a la URL que recibió, con exactamente el Content-Type indicado, y confirme la carga (confirm-affiliate-invoice-upload): la respuesta trae el identificador del documento y su SHA-256.
  3. Presente la factura (submit-affiliate-invoice) con el estado de cuenta (payoutId) y los dos documentos (xmlDocumentId, pdfDocumentId).

La respuesta del tercer paso es awaiting_confirmation, con un confirmUrl y su vencimiento, 7 días después: la factura espera su confirmación. Nada se presenta todavía: la factura aparece en /afiliados, en Facturas enviadas por un agente, y solo cuando usted pulsa Confirmar se revisa contra el estado de cuenta. Si pulsa Rechazar, se descarta. Ningún alcance permite confirmar.

Lo que la API no hace

Postularse y aceptar los términos, la verificación de identidad y tributaria, la cuenta de pago, confirmar una factura y crear o revocar tokens se hacen solo en persona, en /afiliados.

Respuestas de error

Toda negativa trae code, cause y fix. Vea Errores y, código por código, el catálogo de errores.