Skip to content
Notificado
Menu
Create account

API for affiliates

The affiliate account API at /v1/afiliados: the token, the scopes, the reads and the invoice that waits for your confirmation.

Updated:

The affiliate API is at https://www.notificado.co/v1/afiliados. It gives a program of yours (a spreadsheet, your accountant's script) what the MCP for affiliates gives an assistant: your own referral program account, and nothing else.

It is separate from the firms' API (/v1): a firm token reaches nothing under /v1/afiliados, and an affiliate token reaches nothing of a firm.

The token

Created on /afiliados, section Agent access (MCP and API), with a name and its scopes; it is shown once. The same token works for the MCP and for this API. Every call carries it in the Authorization header:

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}` },
});

No operation asks for an affiliate id: the token says who you are, and every answer is about your account.

Response When
401 + WWW-Authenticate: Bearer No token, or an unknown, expired or revoked one.
404 X_ROUTE_NOT_FOUND The operation is outside the token's scopes: it answers as if it did not exist.
403 X_FORBIDDEN The scope covers it, but your account cannot do it (for example, the membership is suspended).
429 X_RATE_LIMITED Too many requests: wait the seconds in Retry-After and repeat.

Scopes

Scope Operations
affiliate:read The summary (code, referral link, funnel and balances), the verification status, the statements, the ledger and the support document download. Each download is recorded.
affiliate:invoices Upload the two files of a statement's electronic invoice and submit it, for you to confirm.
Operation Method and path Scope
Account summary GET /v1/afiliados/my-affiliate-summary affiliate:read
Statements GET /v1/afiliados/my-affiliate-statements affiliate:read
Ledger GET /v1/afiliados/my-affiliate-ledger affiliate:read
Download the support document POST /v1/afiliados/download-affiliate-support-document affiliate:read
Grant a file upload POST /v1/afiliados/request-affiliate-invoice-upload affiliate:invoices
Confirm the upload POST /v1/afiliados/confirm-affiliate-invoice-upload affiliate:invoices
Submit the invoice POST /v1/afiliados/submit-affiliate-invoice affiliate:invoices
Invoices waiting for your confirmation GET /v1/afiliados/my-pending-affiliate-invoices affiliate:invoices

Lists page as on the firms' API: _first=<rows>, and the next page with _after=<nextCursor>. The full list, with parameters, responses and examples, is in the reference: Affiliates. This API's OpenAPI document downloads from https://www.notificado.co/v1/afiliados/openapi.json.

Submitting an invoice

An electronic invoice is submitted in three steps, like an upload in the panel:

  1. Ask for an upload grant for each file (request-affiliate-invoice-upload, with kind einvoice_xml or einvoice_pdf).
  2. Upload the bytes with a PUT to the URL you received, with exactly the Content-Type it names, and confirm the upload (confirm-affiliate-invoice-upload): the answer carries the document id and its SHA-256.
  3. Submit the invoice (submit-affiliate-invoice) with the statement (payoutId) and the two documents (xmlDocumentId, pdfDocumentId).

The third step's answer is awaiting_confirmation, with a confirmUrl and its expiry, 7 days later: the invoice waits for your confirmation. Nothing is submitted yet: the invoice shows on /afiliados, under Invoices sent by an agent, and only when you press Confirm is it checked against the statement. Pressing Reject discards it. No scope can confirm.

What the API does not do

Applying and accepting the terms, the identity and tax verification, the payout account, confirming an invoice and creating or revoking tokens happen only in person, on /afiliados.

Error responses

Every refusal carries code, cause and fix. See Errors and, code by code, the error catalog.