{ "openapi": "3.0.3", "info": { "title": "Nexo", "version": "1.1.0", "description": "Project and environment isolation, integer AOA cents, direct AGT integration. Sandbox simulation has no fiscal validity. Legacy unscoped keys keep the original read/payment scopes; new fiscal writes require explicit scopes. Additive fields may be introduced in v1; consumers must ignore unknown fields." }, "servers": [ { "url": "/api/v1" } ], "paths": { "/health": { "get": { "operationId": "get_health", "summary": "Process health; use /health/ready for dependency readiness.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string" }, "status": { "type": "string" } } } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connection": { "get": { "operationId": "get_connection", "summary": "Confirm the key in use: its id, prefix, environment, scopes, validity and the merchant it is bound to, never the secret. Any valid key may call it, without a scope. A revoked, expired or unknown key gets 401. Use GET /merchants/{merchant}/fiscal/readiness for the fiscal readiness of the merchant.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Connection" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connection/disconnect": { "post": { "operationId": "post_connection_disconnect", "summary": "End the connection of the key in use: revokes this key only and frees its merchant. Project grants and the other keys of the project are untouched. Idempotency-Key is required and the answer is a persistent receipt. If the answer is lost, repeat the request with the same key and the same Idempotency-Key: after the revocation this route alone still accepts that key for that Idempotency-Key and returns the same receipt (200). Any other request with the revoked key, or another Idempotency-Key, gets 401. An expired key may call this route (and only this one) to disconnect. No scope is required.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Disconnection" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 150, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Reuse the same key and body on retries. Scope is project and environment." } ] } }, "/connection/webhook": { "put": { "operationId": "put_connection_webhook", "summary": "Register the callback of the key in use, as a provider callback URL: Nexo calls it for every event this key may see (its merchant, or the whole project for an unbound key). This is the only way to receive events: there is no destination per project. The first registration answers the signing secret once; repeating the same request keeps the secret. An event seen by several keys carries the same X-Pagamentos-Event-Id on each delivery. Registering does not send earlier events. Disconnecting, revoking or expiring the key, or url:null, stops its deliveries, including pending ones. A key only receives payment.* with payments:read and invoice.* with documents:read; registering needs one of them (403 webhook_scope_required), switching off does not.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KeyWebhook" }, "signing_secret": { "type": "string", "description": "Only when the secret is created (first registration) or rotated; null otherwise. Store it with the key: it is never shown again.", "nullable": true } }, "required": [ "data", "signing_secret" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyWebhookInput" } } } } } }, "/connection/webhook/rotate": { "post": { "operationId": "post_connection_webhook_rotate", "summary": "Create a new signing secret for the callback of the key in use and answer it once. Deliveries are signed with the new secret from then on; X-Pagamentos-Key-Id tells which one signed each delivery. 404 webhook_not_configured before the first registration. No scope is required.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KeyWebhook" }, "signing_secret": { "type": "string", "description": "Only when the secret is created (first registration) or rotated; null otherwise. Store it with the key: it is never shown again.", "nullable": true } }, "required": [ "data", "signing_secret" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/merchants": { "get": { "operationId": "get_merchants", "summary": "List merchants explicitly granted to this project.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Merchant" } }, "environment": { "type": "string" } }, "required": [ "data", "environment" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:read" ] }, "post": { "operationId": "post_merchants", "summary": "Create a merchant owned by this project, optionally with its fiscal identity. For platforms onboarding many merchants; requires the explicit merchants:write scope.", "security": [ { "ProjectKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ManagedMerchant" }, "environment": { "type": "string" } }, "required": [ "data", "environment" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ManagedMerchant" }, "environment": { "type": "string" } }, "required": [ "data", "environment" ] } } } } }, "x-required-scopes": [ "merchants:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchant" } } } } } }, "/merchants/{merchant}": { "get": { "operationId": "get_merchants_merchant_", "summary": "Read a merchant with its payment account and fiscal profile in the key environment. Secrets are never returned.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ManagedMerchant" }, "environment": { "type": "string" } }, "required": [ "data", "environment" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:read" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/merchants/{merchant}/account": { "put": { "operationId": "put_merchants_merchant_account", "summary": "Configure the ProxyPay account in the key environment. Owner only; audited with the reason.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MerchantAccount" }, "environment": { "type": "string" } }, "required": [ "data", "environment" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:write" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantAccountInput" } } } } } }, "/merchants/{merchant}/account/test": { "post": { "operationId": "post_merchants_merchant_account_test", "summary": "Test the ProxyPay connection of the configured account.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "environment": { "type": "string" } }, "required": [ "data", "environment" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:write" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/merchants/{merchant}/fiscal": { "put": { "operationId": "put_merchants_merchant_fiscal", "summary": "Create or change the fiscal profile in the key environment. Owner only; audited.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FiscalProfile" }, "environment": { "type": "string" } }, "required": [ "data", "environment" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:write" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalProfileInput" } } } } } }, "/merchants/{merchant}/fiscal/readiness": { "get": { "operationId": "get_merchants_merchant_fiscal_readiness", "summary": "Which document types (FR, FT, RG, NC) can be issued and what is missing.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:read" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/merchants/{merchant}/fiscal/series": { "get": { "operationId": "get_merchants_merchant_fiscal_series", "summary": "List registered fiscal series and series requests.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalSeries" } }, "requests": { "type": "array", "items": { "type": "object" } } }, "required": [ "data", "requests" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:read" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/merchants/{merchant}/fiscal/series/internal": { "post": { "operationId": "post_merchants_merchant_fiscal_series_internal", "summary": "Create a series kept in Nexo (origin internal): no AGT registration, its documents are delivered in the SAF-T file. Repeating the same series returns it; a type and year can have only one active series.", "security": [ { "ProjectKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FiscalSeries" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:write" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalSeriesInternal" } } } } } }, "/merchants/{merchant}/fiscal/series/import": { "post": { "operationId": "post_merchants_merchant_fiscal_series_import", "summary": "Register a series that already exists at AGT. Repeating the same series returns it.", "security": [ { "ProjectKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FiscalSeries" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:write" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalSeriesImport" } } } } } }, "/merchants/{merchant}/fiscal/series/{seriesId}/deactivate": { "post": { "operationId": "post_merchants_merchant_fiscal_series_seriesId_deactivate", "summary": "Stop using a series. Issued numbering is kept; the series is never reactivated.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FiscalSeries" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "merchants:write" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "seriesId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/payments": { "post": { "operationId": "post_payments", "summary": "Create a reference. No fee until an eligible live payment is confirmed.", "security": [ { "ProjectKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "data" ] } } } } }, "x-required-scopes": [ "payments:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 150, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Reuse the same key and body on retries. Scope is project and environment." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayment" } } } } }, "get": { "operationId": "get_payments", "summary": "List project payments in the credential environment.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "payments:read" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "Pages of 50 records." }, { "name": "external_id", "schema": { "type": "string" }, "in": "query" }, { "name": "merchant_id", "schema": { "type": "string", "format": "uuid" }, "in": "query" }, { "name": "status", "schema": { "type": "string", "enum": [ "pending", "paid", "expired", "cancelled", "creating", "awaiting_invoice", "invoice_rejected", "review_required" ] }, "in": "query" }, { "name": "method", "schema": { "type": "string", "enum": [ "reference", "cash", "bank_transfer", "card", "other" ] }, "in": "query" }, { "name": "search", "schema": { "type": "string", "maxLength": 100 }, "in": "query", "description": "external_id, description, reference, payment reference text or the number of the charge document." }, { "name": "from", "schema": { "type": "string", "format": "date" }, "in": "query", "description": "First day of creation, Luanda time." }, { "name": "to", "schema": { "type": "string", "format": "date" }, "in": "query", "description": "Last day of creation, Luanda time." } ] } }, "/payments/{payment}": { "get": { "operationId": "get_payments_payment_", "summary": "Read payment, including late confirmations.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "payments:read" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/payments/{payment}/simulate": { "post": { "operationId": "post_payments_payment_simulate", "summary": "Local/testing mock sandbox only; disabled in production.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "payments:write" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/payments/{payment}/cancellation": { "get": { "operationId": "get_payments_payment_cancellation", "summary": "Read cancellation separately from the bank payment fact.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cancellation" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "payments:read" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "post": { "operationId": "post_payments_payment_cancellation", "summary": "Queue cancellation. This operation is not a refund.", "security": [ { "ProjectKey": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cancellation" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "payments:write" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 150, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Reuse the same key and body on retries. Scope is project and environment." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/payments/{payment}/cancellation/retry": { "post": { "operationId": "post_payments_payment_cancellation_retry", "summary": "Audit a retry of an uncertain cancellation; maximum three retries.", "security": [ { "ProjectKey": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cancellation" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "payments:write" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/payments/{payment}/invoice": { "put": { "operationId": "put_payments_payment_invoice", "summary": "Correct the rejected FT of a charge (status invoice_rejected): a correction FT is sent to AGT and the reference follows its validation. Or correct the rejected FR of a paid charge: a new FR linked to the rejected one is issued and the charge stays paid. Or request an FR for a paid charge created without document; an FT is never issued after payment. Repeating the same data is harmless.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "payments:write" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentInvoice" } } } } } }, "/payments/{payment}/renewal": { "post": { "operationId": "post_payments_payment_renewal", "summary": "Renew an expired, unpaid charge: the same reference is registered again with a new validity. An FT charge that expired before its reference only gets the new validity and returns to awaiting_invoice. Repeating the same validity is harmless.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "payments:write" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Renewal" } } } } } }, "/documents": { "get": { "operationId": "get_documents", "summary": "List fiscal documents, including documents without a payment.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalDocument" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "Pages of 50 records." }, { "name": "merchant_id", "schema": { "type": "string", "format": "uuid" }, "in": "query" }, { "name": "payment_id", "schema": { "type": "string", "format": "uuid" }, "in": "query" }, { "name": "status", "schema": { "type": "string", "enum": [ "queued", "blocked", "submitting", "submitted", "checking", "unknown", "valid", "rejected", "simulated" ] }, "in": "query" }, { "name": "type", "schema": { "type": "string", "enum": [ "FT", "FR", "RG", "NC" ] }, "in": "query" }, { "name": "search", "schema": { "type": "string", "maxLength": 100 }, "in": "query", "description": "Document number, customer name or NIF, or the charge external_id or reference." }, { "name": "from", "schema": { "type": "string", "format": "date" }, "in": "query", "description": "First day, Luanda time." }, { "name": "to", "schema": { "type": "string", "format": "date" }, "in": "query", "description": "Last day, Luanda time." } ] } }, "/documents/{document}": { "get": { "operationId": "get_documents_document_", "summary": "Read an immutable fiscal document and processing status.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FiscalDocument" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/documents/{document}/pdf": { "get": { "operationId": "get_documents_document_pdf", "summary": "Download a valid or simulated PDF. Simulation is visibly marked.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/fiscal/exemption-reasons": { "get": { "operationId": "get_fiscal_exemption_reasons", "summary": "List the active AGT VAT exemption reasons accepted on 0% lines.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VatExemptionReason" } } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:read" ] } }, "/fiscal/taxpayer": { "get": { "operationId": "get_fiscal_taxpayer", "summary": "Look up a customer's NIF at the AGT. 404 when the AGT does not know it; 503 when the lookup is off or the AGT does not answer.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tax_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "vat_regime": { "type": "string", "nullable": true }, "non_resident": { "type": "boolean" } }, "required": [ "tax_id", "non_resident" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Lookup off or AGT not answering.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "tax_id", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{9,15}$" }, "in": "query", "required": true } ] } }, "/fiscal/drafts": { "get": { "operationId": "get_fiscal_drafts", "summary": "List editable fiscal drafts.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Draft" } }, "current_page": { "type": "integer", "format": "int64" }, "last_page": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } }, "required": [ "data", "current_page", "last_page", "total" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "Pages of 50 records." } ] }, "post": { "operationId": "post_fiscal_drafts", "summary": "Create an idempotent draft. Prices and catalogue data are copied.", "security": [ { "ProjectKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Reuse the same key and body on retries. Scope is project and environment." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftInput" } } } } } }, "/fiscal/drafts/{draft}": { "put": { "operationId": "put_fiscal_drafts_draft_", "summary": "Revise a draft with the expected revision to prevent lost updates.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "draft", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftRevision" } } } } } }, "/fiscal/drafts/{draft}/issue": { "post": { "operationId": "post_fiscal_drafts_draft_issue", "summary": "Queue fiscal issuance once. New live capabilities require homologation configuration.", "security": [ { "ProjectKey": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FiscalDocument" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "draft", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "format": "int64", "minimum": 1 } }, "required": [ "revision" ] } } } } } }, "/documents/{document}/balance": { "get": { "operationId": "get_documents_document_balance", "summary": "Read net outstanding balance, credits and payment allocations.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/Allocation" } } }, "required": [ "data", "allocations" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/documents/{document}/allocations": { "post": { "operationId": "post_documents_document_allocations", "summary": "Allocate confirmed funds to FT and create a linked receipt. No extra commercial usage.", "security": [ { "ProjectKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Allocation" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Reuse the same key and body on retries. Scope is project and environment." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationInput" } } } } } }, "/documents/{document}/payment-links": { "get": { "operationId": "get_documents_document_payment_links", "summary": "List payment intentions linked to an invoice.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "post": { "operationId": "post_documents_document_payment_links", "summary": "Link a reference payment to FT; fiscal worker allocates after confirmation and creates RG.", "security": [ { "ProjectKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Reuse the same key and body on retries. Scope is project and environment." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationInput" } } } } } }, "/documents/{document}/payment-links/{link}/retry": { "post": { "operationId": "post_documents_document_payment_links_link_retry", "summary": "Audit a new attempt to allocate a paid intention requiring review.", "security": [ { "ProjectKey": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "link", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/merchants/{merchant}/catalogue/{kind}": { "get": { "operationId": "get_merchants_merchant_catalogue_kind_", "summary": "List project catalogue for merchant and environment.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "current_page": { "type": "integer", "format": "int64" }, "last_page": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } }, "required": [ "data", "current_page", "last_page", "total" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "catalogue:read" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "customers", "items" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "Pages of 50 records." } ] }, "put": { "operationId": "put_merchants_merchant_catalogue_kind_", "summary": "Save a customer or item. Previously issued documents remain unchanged.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "catalogue:write" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "customers", "items" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogueInput" } } } } } }, "/webhooks/proxypay/{account}": { "post": { "operationId": "post_webhooks_proxypay_account_", "summary": "Provider callback. Authenticate the exact raw bytes before processing.", "security": [ { "ProxyPaySignature": [] } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCallback" } } } } } }, "/fiscal/exports": { "get": { "operationId": "get_fiscal_exports", "summary": "List project export jobs.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Export" } }, "current_page": { "type": "integer", "format": "int64" }, "last_page": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } }, "required": [ "data", "current_page", "last_page", "total" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "reports:read" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "Pages of 50 records." } ] }, "post": { "operationId": "post_fiscal_exports", "summary": "Snapshot a project report for asynchronous generation, bounded to one fiscal year and 5000 documents/payments.", "security": [ { "ProjectKey": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Export" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "reports:read" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Reuse the same key and body on retries. Scope is project and environment." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } } } }, "/fiscal/exports/{export}": { "get": { "operationId": "get_fiscal_exports_export_", "summary": "Read generation status and checksum.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Export" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "reports:read" ], "parameters": [ { "name": "export", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/fiscal/exports/{export}/regenerate": { "post": { "operationId": "post_fiscal_exports_export_regenerate", "summary": "Generate again an export that expired or failed, from the documents as they are now. An export still pending is returned as is; one still available answers 409.", "security": [ { "ProjectKey": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Export" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "reports:read" ], "parameters": [ { "name": "export", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/fiscal/exports/{export}/download": { "get": { "operationId": "get_fiscal_exports_export_download", "summary": "Download verified report; availability expires after seven days.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Content-SHA256": { "schema": { "type": "string" }, "description": "SHA-256 of the returned unencrypted bytes." } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "reports:read" ], "parameters": [ { "name": "export", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/fiscal/saft": { "get": { "operationId": "get_fiscal_saft", "summary": "List the SAF-T files of the companies the project owns.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Export" } }, "current_page": { "type": "integer", "format": "int64" }, "last_page": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } }, "required": [ "data", "current_page", "last_page", "total" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "saft:read" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "Pages of 50 records." } ] }, "post": { "operationId": "post_fiscal_saft", "summary": "Request the SAF-T file of a company the project owns, for a period of one fiscal year. It carries the documents of internal series, is generated asynchronously and is refused when the period has none.", "security": [ { "ProjectKey": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Export" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "saft:read" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Reuse the same key and body on retries. Scope is project and environment." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaftRequest" } } } } } }, "/fiscal/saft/{export}": { "get": { "operationId": "get_fiscal_saft_export_", "summary": "Read the generation status, checksum and schema validation of a SAF-T file. summary.validation lists the translated schema errors; a file with errors is still delivered.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Export" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "saft:read" ], "parameters": [ { "name": "export", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/fiscal/saft/{export}/regenerate": { "post": { "operationId": "post_fiscal_saft_export_regenerate", "summary": "Generate again a SAF-T file that expired or failed, from the documents as they are now. A pending one is returned as is; one still available answers 409.", "security": [ { "ProjectKey": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Export" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "saft:read" ], "parameters": [ { "name": "export", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/fiscal/saft/{export}/download": { "get": { "operationId": "get_fiscal_saft_export_download", "summary": "Download the SAF-T file: a zip with the XML and its SHA-256 by default, or the XML with format=xml. Available for seven days.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "X-Content-SHA256": { "schema": { "type": "string" }, "description": "SHA-256 of the returned bytes (the zip, or the XML)." }, "X-SAFT-XML-SHA256": { "schema": { "type": "string" }, "description": "SHA-256 of the XML inside the zip." }, "X-SAFT-Validation": { "schema": { "type": "string", "enum": [ "valid", "invalid" ] }, "description": "Whether the file passed the schema validation." } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "saft:read" ], "parameters": [ { "name": "export", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "zip", "xml" ], "default": "zip" } } ] } }, "/fiscal/cnbs-codes": { "get": { "operationId": "get_fiscal_cnbs_codes", "summary": "Search the active CNBS codes accepted in cnbs_code, by the start of the code or words of the description.", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CnbsCode" } }, "required_from": { "type": "string", "format": "date", "description": "Issue date from which every FT and FR line must carry a CNBS code." }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "data", "required_from", "current_page", "last_page", "total" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ] } }, "/documents/{document}/rectification": { "post": { "operationId": "post_documents_document_rectification", "summary": "Rectify a validated FT or FR with a credit note (NC) of the whole document. Repeating it returns the same NC (200).", "security": [ { "ProjectKey": [] } ], "responses": { "200": { "description": "The NC that already rectified this document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FiscalDocument" } }, "required": [ "data" ] } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FiscalDocument" } }, "required": [ "data" ] } } } }, "401": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed; inspect error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RectificationInput" } } } } } } }, "components": { "securitySchemes": { "ProjectKey": { "type": "http", "scheme": "bearer", "description": "One project/environment, named scopes, optional expiry; plaintext shown once." }, "ProxyPaySignature": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "Hex HMAC SHA-256 of raw body using the account ProxyPay key." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error" ] }, "Meta": { "type": "object", "properties": { "current_page": { "type": "integer", "format": "int64" }, "last_page": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } }, "required": [ "current_page", "last_page", "total" ] }, "Customer": { "type": "object", "properties": { "tax_id": { "type": "string", "pattern": "^[A-Z0-9]{9,15}$" }, "name": { "type": "string", "maxLength": 160 }, "address": { "type": "string", "maxLength": 500 }, "country": { "type": "string", "enum": [ "AO" ] } }, "required": [ "tax_id", "name", "address", "country" ] }, "InvoiceItem": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 60 }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100000 }, "unit_amount_minor": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9999999999 }, "vat_rate": { "type": "integer", "format": "int64", "enum": [ 14, 7, 5, 1, 0 ], "description": "Angolan VAT rate." }, "tax_code": { "type": "string", "enum": [ "NOR", "RED", "ISE" ], "description": "Optional. Derived from vat_rate (0 ISE, 14 NOR, 7/5/1 RED); when sent it must match." }, "operation_type": { "type": "string", "enum": [ "SE", "SS", "STP", "SR", "SIF", "SHS", "ST", "SG", "TB", "AS", "QT", "RD" ] }, "exemption_code": { "type": "string", "pattern": "^M[0-9]{2}$", "description": "Required for 0% and forbidden otherwise: an active code from GET /fiscal/exemption-reasons.", "nullable": true }, "cnbs_code": { "type": "string", "pattern": "^[0-9]{8}$", "description": "CNBS code (INE classification of goods and services) from GET /fiscal/cnbs-codes, sent to the AGT as productCode instead of code. Optional until fiscal.cnbs_required_from (2027-01-01); from that date every FT and FR line must carry an active code.", "nullable": true } }, "required": [ "code", "description", "quantity", "unit_amount_minor", "vat_rate", "operation_type" ] }, "DecimalItem": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 60 }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "oneOf": [ { "type": "integer", "format": "int64", "minimum": 1, "maximum": 99999 }, { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,4})(?:\\.[0-9]{1,4})?$" } ] }, "unit_amount_minor": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9999999999 }, "vat_rate": { "oneOf": [ { "type": "integer", "format": "int64", "enum": [ 14, 7, 5, 1, 0 ] }, { "type": "string", "pattern": "^(?:14|7|5|1|0)(?:\\.0{1,2})?$" } ], "description": "Angolan VAT rate: 14, 7, 5, 1 or 0." }, "tax_code": { "type": "string", "enum": [ "NOR", "RED", "ISE" ], "description": "Optional. Derived from vat_rate (0 ISE, 14 NOR, 7/5/1 RED); when sent it must match." }, "operation_type": { "type": "string", "enum": [ "SE", "SS", "STP", "SR", "SIF", "SHS", "ST", "SG", "TB", "AS", "QT", "RD" ] }, "exemption_code": { "type": "string", "pattern": "^M[0-9]{2}$", "description": "Required for 0% and forbidden otherwise: an active code from GET /fiscal/exemption-reasons.", "nullable": true }, "discount_bps": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 10000 }, "unit_of_measure": { "type": "string", "maxLength": 20 }, "original_line": { "type": "integer", "format": "int64", "minimum": 1, "description": "Required for NC: one-based line in the original document." }, "catalogue_item_id": { "type": "string", "format": "uuid" }, "cnbs_code": { "type": "string", "pattern": "^[0-9]{8}$", "description": "CNBS code (INE classification of goods and services) from GET /fiscal/cnbs-codes, sent to the AGT as productCode instead of code. Optional until fiscal.cnbs_required_from (2027-01-01); from that date every FT and FR line must carry an active code.", "nullable": true } }, "required": [ "code", "description", "quantity", "unit_amount_minor", "vat_rate", "operation_type" ] }, "VatExemptionReason": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^M[0-9]{2}$" }, "document_mention": { "type": "string" }, "legal_basis": { "type": "string", "nullable": true }, "description": { "type": "string" }, "exemption_type": { "type": "string", "enum": [ "incompleta_interna", "incompleta_importacao", "completa", "regime_especial_aduaneiro" ] } }, "required": [ "code", "document_mention", "legal_basis", "description", "exemption_type" ] }, "InvoiceRequest": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItem" }, "minItems": 1, "maxItems": 100 }, "payment_method": { "type": "string", "enum": [ "reference" ] } }, "required": [ "customer", "items", "payment_method" ] }, "CreatePayment": { "type": "object", "properties": { "merchant_id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string", "maxLength": 150 }, "amount_minor": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9999999999 }, "currency": { "type": "string", "enum": [ "AOA" ] }, "description": { "type": "string", "maxLength": 255 }, "expires_at": { "type": "string", "format": "date-time", "description": "Future ISO-8601 instant, maximum 90 days. Defaults to 24 hours. Not accepted with a recorded method." }, "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 500 } }, "document_type": { "type": "string", "enum": [ "FR", "FT" ], "description": "Fiscal document of the charge; required with invoice_data. Omit both for no document. FR: reference now, factura-recibo after payment. FT: invoice sent to AGT now, reference only after validation (status awaiting_invoice), receipt (RG) after payment." }, "invoice_data": { "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" } ], "description": "Customer and items of the document; required with document_type." }, "order_data": { "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" } ], "description": "Same customer and items as invoice_data, recorded without issuing a factura-recibo. Mutually exclusive with invoice_data." }, "paid_at": { "type": "string", "format": "date-time", "description": "Required with a recorded method and forbidden otherwise: when the money was received, with seconds and offset, in the past and within 365 days." }, "method": { "type": "string", "enum": [ "reference", "cash", "bank_transfer", "card", "other" ], "default": "reference", "description": "reference creates a ProxyPay reference. cash, bank_transfer, card (card terminal) and other record money the merchant already received: the payment is created paid, with no reference and no expiry, and needs no ProxyPay account. document_type may then be FR or absent, never FT; an FT is settled by allocating the payment with POST /documents/{document}/allocations." }, "method_reference": { "type": "string", "maxLength": 100, "nullable": true, "description": "Optional, recorded methods only: receipt, transfer or terminal reference." } }, "required": [ "merchant_id", "external_id", "amount_minor", "currency", "description" ] }, "DocumentSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "FR", "FT", "RG" ] }, "status": { "type": "string" }, "number": { "type": "string", "nullable": true }, "simulated": { "type": "boolean" } }, "required": [ "id", "type", "status", "number", "simulated" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "amount_minor": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9999999999 }, "currency": { "type": "string", "enum": [ "AOA" ] }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_invoice", "invoice_rejected", "creating", "pending", "expired", "paid", "cancelled" ], "description": "awaiting_invoice: FT sent to AGT, no reference yet. invoice_rejected: AGT rejected the FT; correct it with PUT /payments/{payment}/invoice." }, "method": { "type": "string", "enum": [ "reference", "cash", "bank_transfer", "card", "other" ], "description": "reference for a ProxyPay charge; any other value for a payment recorded by the merchant." }, "provider": { "type": "string", "enum": [ "mock", "proxypay" ], "nullable": true, "description": "null for a payment recorded by the merchant." }, "simulated": { "type": "boolean" }, "reference": { "type": "object", "properties": { "entity": { "type": "string" }, "number": { "type": "string" } }, "required": [ "entity", "number" ], "nullable": true }, "expires_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object" }, "document_type": { "type": "string", "enum": [ "FR", "FT" ], "nullable": true }, "invoice_requested": { "type": "boolean" }, "fiscal_document": { "allOf": [ { "$ref": "#/components/schemas/DocumentSummary" } ], "description": "FR of the charge, or its current FT.", "nullable": true }, "receipt": { "allOf": [ { "$ref": "#/components/schemas/DocumentSummary" } ], "description": "RG issued after payment of an FT charge.", "nullable": true }, "documents": { "type": "array", "description": "Every document of the charge: FT or FR, the receipts (RG) that settled it and the credit notes (NC) that rectified them. A rejected document already replaced by a correction is left out.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "FT", "FR", "RG", "NC" ] }, "number": { "type": "string", "nullable": true }, "status": { "type": "string" }, "simulated": { "type": "boolean" } } } }, "items": { "type": "array", "description": "Only in GET /payments/{payment}. The lines of the invoice (FT or FR) the charge pays for, as issued.", "items": { "type": "object" } }, "method_reference": { "type": "string", "nullable": true } }, "required": [ "id", "merchant_id", "external_id", "environment", "amount_minor", "currency", "status", "method", "method_reference", "provider", "simulated", "reference", "expires_at", "paid_at", "created_at", "metadata", "document_type", "invoice_requested", "fiscal_document", "receipt" ] }, "FiscalDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payment_id": { "type": "string", "format": "uuid", "nullable": true }, "merchant_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "type": { "type": "string", "enum": [ "FR", "FT", "NC", "RG" ] }, "number": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "queued", "blocked", "submitting", "submitted", "checking", "unknown", "valid", "rejected", "simulated" ] }, "simulated": { "type": "boolean" }, "fiscal_valid": { "type": "boolean" }, "snapshot": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" }, "items": { "type": "array", "items": { "type": "object" } }, "totals": { "type": "object", "properties": { "net_minor": { "type": "integer", "format": "int64" }, "tax_minor": { "type": "integer", "format": "int64" }, "gross_minor": { "type": "integer", "format": "int64" } }, "required": [ "net_minor", "tax_minor", "gross_minor" ] } } }, "issued_at": { "type": "string", "format": "date-time", "nullable": true }, "validated_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error_code": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "original_document_id": { "type": "string", "format": "uuid", "nullable": true }, "corrects_document_id": { "type": "string", "format": "uuid", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "calculation_version": { "type": "string", "nullable": true }, "pdf_url": { "type": "string", "nullable": true }, "settlements": { "type": "array", "description": "The receipts (RG) that settled an FT (relation settled_by) or the FT an RG settles (relation settles), with the amount of each.", "items": { "type": "object", "properties": { "relation": { "type": "string", "enum": [ "settles", "settled_by" ] }, "id": { "type": "string", "format": "uuid" }, "number": { "type": "string", "nullable": true }, "type": { "type": "string" }, "amount_minor": { "type": "integer", "format": "int64" } } } }, "linked": { "type": "object", "description": "Listing only. The document this one is tied to by a rectification: a credit note points to the document it rectifies, a rectified FT/FR to its credit note.", "properties": { "relation": { "type": "string", "enum": [ "rectifies", "rectified_by" ] }, "id": { "type": "string", "format": "uuid" }, "number": { "type": "string", "nullable": true }, "type": { "type": "string" } }, "nullable": true }, "payment": { "type": "object", "description": "The charge the document belongs to; for an FT or RG settled by allocation, the charge that paid it.", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "method": { "type": "string" }, "amount_minor": { "type": "integer", "format": "int64" }, "currency": { "type": "string" } }, "nullable": true }, "last_error_message": { "type": "string", "nullable": true, "description": "The AGT explanation for last_error_code, when the AGT gave one." }, "rectification": { "type": "object", "description": "Only in GET /documents/{document}. Whether the document can be rectified with a full NC, and the NC that rectified it.", "properties": { "allowed": { "type": "boolean" }, "blocked_reason": { "type": "string", "nullable": true, "description": "Why an FT or FR cannot be rectified, for example an FT already settled by a receipt (RG)." }, "credit_note": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string", "nullable": true }, "status": { "type": "string" } } } } } }, "required": [ "id", "payment_id", "merchant_id", "environment", "type", "status", "simulated", "fiscal_valid", "snapshot" ] }, "DraftInput": { "type": "object", "properties": { "merchant_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "FT", "NC", "FR" ], "description": "FR only for correction of a rejected FR. Ordinary FR starts with a payment." }, "customer": { "$ref": "#/components/schemas/Customer" }, "customer_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DecimalItem" }, "minItems": 1, "maxItems": 100 }, "due_date": { "type": "string", "format": "date" }, "original_document_id": { "type": "string", "format": "uuid" }, "corrects_document_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 5, "maxLength": 60 }, "revision": { "type": "integer", "format": "int64", "minimum": 1 } }, "required": [ "merchant_id", "type", "items" ] }, "Draft": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "client_application_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string" }, "document_type": { "type": "string" }, "revision": { "type": "integer", "format": "int64" }, "data": { "type": "object" }, "issued_document_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "merchant_id", "environment", "document_type", "revision", "data" ] }, "DraftRevision": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" }, "customer_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DecimalItem" }, "minItems": 1, "maxItems": 100 }, "due_date": { "type": "string", "format": "date" }, "original_document_id": { "type": "string", "format": "uuid" }, "corrects_document_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 5, "maxLength": 60 }, "revision": { "type": "integer", "format": "int64", "minimum": 1 } }, "required": [ "items", "revision" ] }, "Cancellation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payment_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "requested", "sending", "unknown", "cancelled", "failed", "paid" ] }, "attempts": { "type": "integer", "format": "int64" }, "retries": { "type": "integer", "format": "int64" }, "result_code": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "payment_id", "status" ] }, "Renewal": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time", "description": "New validity with seconds and offset, future and at most 90 days ahead. Amount, customer and items never change." } }, "required": [ "expires_at" ] }, "PaymentInvoice": { "type": "object", "properties": { "invoice_data": { "allOf": [ { "$ref": "#/components/schemas/InvoiceRequest" } ], "description": "Corrected customer and items (same total). Optional for a paid charge with order_data, which is then reused." } } }, "Reason": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "reason" ] }, "AllocationInput": { "type": "object", "properties": { "payment_id": { "type": "string", "format": "uuid" }, "amount_minor": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9999999999 } }, "required": [ "payment_id", "amount_minor" ] }, "Allocation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payment_id": { "type": "string", "format": "uuid" }, "fiscal_document_id": { "type": "string", "format": "uuid" }, "receipt_document_id": { "type": "string", "format": "uuid" }, "amount_minor": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9999999999 } }, "required": [ "id", "payment_id", "fiscal_document_id", "amount_minor" ] }, "CatalogueInput": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 60 }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Customer" }, { "$ref": "#/components/schemas/DecimalItem" } ] }, "active": { "type": "boolean" } }, "required": [ "code", "data" ] }, "Merchant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "slug", "name" ] }, "CreateMerchant": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$", "description": "Your identifier for the merchant. Repeating the same slug and name returns the existing merchant (200)." }, "name": { "type": "string", "maxLength": 160 }, "tax_id": { "type": "string", "pattern": "^[A-Z0-9]{9,15}$", "description": "Optional fiscal identity for the key environment; requires legal_name and address." }, "legal_name": { "type": "string", "maxLength": 160 }, "address": { "type": "string", "maxLength": 500 } }, "required": [ "slug", "name" ] }, "MerchantAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "provider": { "type": "string", "enum": [ "mock", "proxypay" ] }, "entity": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "reconciliation_enabled": { "type": "boolean" }, "has_api_key": { "type": "boolean", "description": "The ProxyPay key is never returned." } }, "required": [ "id", "merchant_id", "environment", "provider", "active", "has_api_key" ] }, "MerchantAccountInput": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "proxypay", "mock" ], "description": "mock only in local/testing sandbox." }, "entity": { "type": "string", "pattern": "^[0-9]{1,5}$" }, "api_key": { "type": "string", "maxLength": 4096, "description": "ProxyPay key. Omit to keep the stored key; it is never returned." }, "reconciliation_enabled": { "type": "boolean" }, "reason": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "provider", "reason" ] }, "FiscalProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "tax_id": { "type": "string" }, "legal_name": { "type": "string" }, "address": { "type": "string" }, "eac_code": { "type": "string", "nullable": true }, "commercial_registry": { "type": "string", "nullable": true }, "tax_entity": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "simulated": { "type": "boolean" }, "has_private_key": { "type": "boolean", "description": "The private key is never returned." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "merchant_id", "environment", "tax_id", "legal_name", "address", "enabled", "simulated", "has_private_key" ] }, "FiscalProfileInput": { "type": "object", "properties": { "tax_id": { "type": "string", "pattern": "^[A-Z0-9]{9,15}$" }, "legal_name": { "type": "string", "maxLength": 160 }, "address": { "type": "string", "maxLength": 500 }, "eac_code": { "type": "string", "pattern": "^[0-9]{5}$", "nullable": true }, "commercial_registry": { "type": "string", "maxLength": 50, "description": "Commercial registry number, written as CompanyID in the SAF-T header.", "nullable": true }, "tax_entity": { "type": "string", "maxLength": 20, "description": "TaxEntity of the SAF-T header. Empty means Global.", "nullable": true }, "city": { "type": "string", "maxLength": 50, "description": "City of the fiscal address, for the SAF-T header.", "nullable": true }, "enabled": { "type": "boolean", "description": "Requires the private key unless simulated." }, "simulated": { "type": "boolean", "description": "Local sandbox only." }, "issuer_private_key": { "type": "string", "maxLength": 16384, "description": "PEM RSA key, at least 2048 bits. Omit to keep the stored key; it is never returned.", "nullable": true } }, "required": [ "tax_id", "legal_name", "address" ] }, "ManagedMerchant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "account": { "allOf": [ { "$ref": "#/components/schemas/MerchantAccount" } ], "nullable": true }, "fiscal_profile": { "allOf": [ { "$ref": "#/components/schemas/FiscalProfile" } ], "nullable": true } }, "required": [ "id", "slug", "name", "account", "fiscal_profile" ] }, "FiscalSeries": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "document_type": { "type": "string", "enum": [ "FR", "FT", "RG", "NC" ] }, "series_code": { "type": "string" }, "year": { "type": "integer", "format": "int64" }, "establishment": { "type": "string" }, "first_number": { "type": "integer", "format": "int64" }, "last_number": { "type": "integer", "format": "int64" }, "next_number": { "type": "integer", "format": "int64" }, "active": { "type": "boolean" }, "origin": { "type": "string", "enum": [ "agt", "internal" ], "description": "agt: communicated to the AGT one by one. internal: kept in Nexo and delivered in the SAF-T file. It never changes once the series has documents." } }, "required": [ "id", "document_type", "series_code", "year", "next_number", "active", "origin" ] }, "FiscalSeriesInternal": { "type": "object", "properties": { "document_type": { "type": "string", "enum": [ "FR", "FT", "RG", "NC" ] }, "year": { "type": "integer", "format": "int64", "minimum": 2000, "maximum": 2099 }, "series_code": { "type": "string", "minLength": 3, "maxLength": 46, "description": "Defaults to the type followed by the year.", "nullable": true }, "establishment": { "type": "string", "maxLength": 200, "description": "Defaults to SEDE.", "nullable": true }, "first_number": { "type": "integer", "format": "int64", "minimum": 1, "description": "Defaults to 1." }, "last_number": { "type": "integer", "format": "int64", "minimum": 1, "description": "Defaults to 999999999999." }, "reason": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "document_type", "year", "reason" ] }, "FiscalSeriesImport": { "type": "object", "properties": { "document_type": { "type": "string", "enum": [ "FR", "FT", "RG", "NC" ] }, "year": { "type": "integer", "format": "int64", "minimum": 2000, "maximum": 2099 }, "series_code": { "type": "string", "minLength": 2, "maxLength": 46 }, "first_number": { "type": "integer", "format": "int64", "minimum": 1 }, "last_number": { "type": "integer", "format": "int64", "minimum": 1 }, "next_number": { "type": "integer", "format": "int64", "minimum": 1 }, "establishment": { "type": "string", "maxLength": 200 }, "registered": { "type": "boolean", "enum": [ true ], "description": "Confirms the series is already registered at AGT. Nexo does not create it." }, "reason": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "document_type", "year", "series_code", "first_number", "last_number", "next_number", "establishment", "registered", "reason" ] }, "ProviderCallback": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "reference_id": { "type": "integer", "format": "int64" }, "entity_id": { "type": "integer", "format": "int64" }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "datetime": { "type": "string", "format": "date-time" } }, "required": [ "id", "reference_id", "entity_id", "amount", "datetime" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "required": [ "id", "type", "created_at", "data" ] }, "ExportRequest": { "type": "object", "properties": { "merchant_id": { "type": "string", "format": "uuid" }, "format": { "type": "string", "enum": [ "json_report" ], "description": "Issuer-wide SAF-T is restricted to the authorised owner in the portal." }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } }, "required": [ "merchant_id", "format", "start_date", "end_date" ] }, "Export": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string" }, "format": { "type": "string" }, "scope": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "complete", "failed", "expired" ] }, "summary": { "type": "object" }, "sha256": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "error_code": { "type": "string", "nullable": true } }, "required": [ "id", "merchant_id", "environment", "format", "scope", "status" ] }, "Connection": { "type": "object", "properties": { "credential_id": { "type": "string", "format": "uuid" }, "key_prefix": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "active" ] }, "merchant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "description": "The merchant this key is bound to, or null when the key reaches every merchant of the project. slug and name only with merchants:read.", "nullable": true }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/KeyWebhook" } ], "description": "The callback this key registered with PUT /connection/webhook, or null.", "nullable": true } }, "required": [ "credential_id", "key_prefix", "environment", "scopes", "expires_at", "status", "merchant" ] }, "KeyWebhook": { "type": "object", "properties": { "url": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "signing_key_id": { "type": "string", "format": "uuid", "description": "Sent as X-Pagamentos-Key-Id in each delivery: tells which secret signed it.", "nullable": true } }, "required": [ "url", "enabled", "signing_key_id" ] }, "KeyWebhookInput": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "description": "Public HTTPS address. null switches the callback off and keeps the secret.", "nullable": true } }, "required": [ "url" ] }, "Disconnection": { "type": "object", "properties": { "receipt_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "revoked" ] }, "credential_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "merchant_id": { "type": "string", "format": "uuid", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time" } }, "required": [ "receipt_id", "status", "credential_id", "environment", "merchant_id", "revoked_at" ] }, "SaftRequest": { "type": "object", "properties": { "merchant_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date", "description": "Within the same fiscal year as start_date." } }, "required": [ "merchant_id", "start_date", "end_date" ] }, "CnbsCode": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9]{8}$" }, "description": { "type": "string" } }, "required": [ "code", "description" ] }, "RectificationInput": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 60, "description": "Reason sent to the AGT in the credit note (referenceInfo.reason)." } } } } }, "x-event-envelope": { "$ref": "#/components/schemas/Event" }, "x-events": [ "payment.paid", "payment.expired", "payment.cancel_requested", "payment.cancelled", "payment.cancel_uncertain", "payment.renewed", "payment.reference_ready", "payment.invoice_rejected", "payment.invoice_credited", "invoice.valid", "invoice.rejected", "invoice.simulated" ], "x-webhook-signature": { "algorithm": "HMAC-SHA256", "signed_value": "X-Pagamentos-Timestamp + \".\" + exact raw body", "headers": [ "X-Pagamentos-Event-Id", "X-Pagamentos-Timestamp", "X-Pagamentos-Signature", "X-Pagamentos-Key-Id" ], "deduplication": "Event UUID, unchanged during retries/backfill. Keys rotate independently per environment." } }