{ "openapi": "3.1.0", "info": { "title": "API de Antecipação de Recebíveis — Zemo Capital", "description": "API V2 para originadores realizarem antecipação de recebíveis.\n\n> ⚠️ **Teste interativo (\"Testar no navegador\")**\n> As requisições vão direto para o servidor selecionado, sem proxy de terceiros. Para homologar, selecione **Sandbox** e use apenas credenciais `zk_test_*`.\n> Obtenha o JWT executando `POST /v1/auth/token` com o corpo JSON e informe o `access_token` como Bearer nas demais operações.", "version": "1.6.0" }, "paths": { "/v1/health": { "get": { "tags": [ "health" ], "summary": "Service health check", "description": "Returns service status, env, version, and uptime info. Used by ALB target group, ECS healthcheck, and smoke tests.", "operationId": "health_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Health V1 Health Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. O corpo e o MESMO do health check, com `status` em `degraded` — esta rota nao usa o envelope `detail`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst health = await zemo.request<{ status: string; env: string }>(\n \"GET\",\n \"/v1/health\",\n);\nconsole.log(health.status, health.env);\n" } ] } }, "/v1/health/deep": { "get": { "tags": [ "health" ], "summary": "Protected deep health check", "operationId": "deep_health_v1_health_deep_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Deep Health V1 Health Deep Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Health profundo (DB + dependencias)\nconst health = await zemo.request(\"GET\", \"/v1/health/deep\");\nconsole.log(health);\n" } ] } }, "/v1/flow": { "get": { "tags": [ "flow" ], "summary": "Fluxo da API", "description": "Retorna a descricao machine-readable do fluxo da API. Use para entender a sequencia de chamadas necessarias para completar uma antecipacao.", "operationId": "get_flow_v1_flow_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Visao consolidada do fluxo financeiro do originador\nconst flow = await zemo.request(\"GET\", \"/v1/flow\");\nconsole.log(flow);\n" } ] } }, "/v1/auth/login": { "post": { "tags": [ "auth" ], "summary": "Login", "operationId": "login_v1_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Credenciais invalidas — inclui a conta BLOQUEADA sem senha provada. E-mail inexistente, senha errada e conta bloqueada com senha errada sao indistinguiveis: a rota nao e oraculo de existencia de e-mail.\n\nCodigos possiveis nesta operacao: `invalid_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "423": { "description": "Credencial CORRETA e conta bloqueada (30 minutos apos 5 falhas de login). So quem prova a senha ve este codigo.\n\nCodigos possiveis nesta operacao: `user_locked`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `authentication_temporarily_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// /v1/auth/login e para SESSOES DE USUARIO (portal), nao para integracao\n// servidor-a-servidor. Nesta, use as credenciais de API no construtor\n// (acima). Se precisar mesmo do login:\nconst session = await zemo.request(\"POST\", \"/v1/auth/login\", {\n body: { email: \"usuario@empresa.com\", password: \"...\" },\n});\n" } ] } }, "/v1/auth/me": { "get": { "tags": [ "auth" ], "summary": "Me", "operationId": "me_v1_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Me V1 Auth Me Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Identidade por tras das credenciais atuais\nconst identity = await zemo.request(\"GET\", \"/v1/auth/me\");\nconsole.log(identity);\n" } ] } }, "/v1/auth/token": { "post": { "tags": [ "auth" ], "summary": "Trocar credenciais de API por JWT (Client Credentials)", "description": "Client Credentials flow: exchange client_id + client_secret for a short-lived JWT RS256 token. Use the returned token in subsequent requests via Authorization: Bearer . TTL: 15 minutes.", "operationId": "exchange_token_v1_auth_token_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" }, "examples": { "default": { "summary": "Exemplo", "value": { "client_id": "zk_test_9f2c1a4b8e7d6053", "client_secret": "" } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" }, "examples": { "default": { "summary": "Exemplo", "value": { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..", "token_type": "bearer", "expires_in": 900, "scopes": [ "stock:write", "simulation:create", "operation:create", "operation:read", "webhook:write" ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "client_id ou client_secret de API invalido\n\nCodigos possiveis nesta operacao: `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "default": { "summary": "Exemplo", "value": { "detail": "invalid_client_credentials" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `authentication_temporarily_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// O SDK troca as credenciais por um JWT de curta duracao automaticamente\n// (cache + refresh transparentes). Nao chame /v1/auth/token manualmente.\nconst zemo = new Zemo({\n clientId: \"zk_test_...\", // zk_test_* -> sandbox, zk_live_* -> producao\n clientSecret: \"sk_test_...\",\n});\n\n// Qualquer chamada a seguir ja sai autenticada:\nconst me = await zemo.originator.me();\nconsole.log(me.legalName);\n" } ], "security": [] } }, "/v1/originators/me": { "get": { "tags": [ "originators" ], "summary": "Obter meu originador", "description": "Retorna dados do originador autenticado.", "operationId": "get_my_originator_v1_originators_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginatorMe" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `originator_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst me = await zemo.originator.me();\nconsole.log(me.legalName, me.document);\n" } ], "x-required-scope": "originator:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/stock": { "get": { "tags": [ "stock" ], "summary": "Listar estoque de recebiveis", "description": "Retorna recebiveis registrados, filtrados por status, cedente ou sacado.", "operationId": "list_stock_items_v1_stock_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "assignor_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" } }, { "name": "payer_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payer Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Uma pagina:\nconst page = await zemo.stock.page({ status: \"IN_STOCK\", limit: 50 });\nconsole.log(page.total, page.items.length);\n\n// Ou itere TODOS os itens (paginacao transparente):\nfor await (const item of zemo.stock.query({ status: \"IN_STOCK\" })) {\n console.log(item.id, item.externalId);\n}\n" } ], "x-required-scope": "stock:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "post": { "tags": [ "stock" ], "summary": "Registrar recebivel no estoque", "description": "Cadastra um recebivel (NF, duplicata, contrato) como potencial antecipacao.", "operationId": "register_stock_item_v1_stock_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockItemCreate" }, "examples": { "default": { "summary": "Exemplo", "value": { "assignor_id": "01994c1e-1a00-7000-9000-000000000001", "payer_id": "01994c1e-2b00-7000-9000-000000000002", "external_id": "NF-2026-001", "backing_type": "NFE", "gross_face_value": "10000.00", "net_face_value": "10000.00", "due_date": "2026-10-07", "pre_authorized": true } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockItemCreateResponse" }, "examples": { "default": { "summary": "Exemplo", "value": { "id": "01994c1e-8a10-7000-9000-0000000000a1", "external_id": "NF-2026-001", "status": "IN_STOCK", "created_at": "2026-07-29T14:30:00Z" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_required`, `VOCABULARY_CONFLICT`, `DEDUCTIONS_REQUIRED_WITH_GROSS`, `VALUE_DECOMPOSITION_MISMATCH`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `assignor_not_found`, `payer_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `external_id_already_exists`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "default": { "summary": "Exemplo", "value": { "detail": "external_id_already_exists" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "OBRIGATORIA nesta rota: sem o header a requisicao e recusada com `422` `idempotency_key_required`, antes de qualquer efeito. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Registrar um recebivel no estoque\nconst item = await zemo.stock.create({\n assignorId: \"\",\n payerId: \"\",\n externalId: \"NF-2026-001\",\n grossFaceValue: 12000.0,\n netFaceValue: 10000.0,\n dueDate: \"2026-08-15\",\n preAuthorized: true,\n});\nconsole.log(item.id, item.status);\n" }, { "lang": "Python", "label": "SDK Python (zemo)", "source": "import zemo\n\n# Autenticacao de API por Client Credentials\n# (o SDK troca as credenciais por um JWT de curta duracao)\nzemo.user = zemo.Originator(\n client_id=\"zk_test_...\",\n client_secret=\"sk_test_...\",\n environment=\"https://receivables-api-sandbox.zemocapital.com\",\n)\n\n# Registrar um recebivel no estoque\nitem = zemo.Stock.create(\n assignor_id=\"\",\n payer_id=\"\",\n external_id=\"NF-001\",\n gross_future_value=10000.00,\n # Exigido junto do bruto (envie 0 se nao houver deducoes):\n gross_future_value_deductions=0.00,\n net_future_value=10000.00,\n due_date=\"2026-08-15\",\n pre_authorized=True,\n)\nprint(item.id)\n" } ], "x-required-scope": "stock:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/stock/{item_id}": { "get": { "tags": [ "stock" ], "summary": "Obter item do estoque", "operationId": "get_stock_item_v1_stock__item_id__get", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockItemDetail" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `stock_item_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst item = await zemo.stock.get(\"\");\nconsole.log(item.status, item.netFaceValue);\n" } ], "x-required-scope": "stock:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "patch": { "tags": [ "stock" ], "summary": "Editar item do estoque", "description": "Atualiza campos de um recebivel em status IN_STOCK. Envie apenas os campos que deseja alterar.", "operationId": "update_stock_item_v1_stock__item_id__patch", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockItemUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Stock Item V1 Stock Item Id Patch" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `no_fields_to_update`, `STOCK_ITEM_NFV_ABOVE_GROSS`, `VOCABULARY_CONFLICT`, `DEDUCTIONS_REQUIRED_WITH_GROSS`, `VALUE_DECOMPOSITION_MISMATCH`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `assignor_not_found`, `payer_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `stock_item_not_found_or_not_in_stock`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst item = await zemo.stock.update(\"\", {\n netFaceValue: 9500.0,\n dueDate: \"2026-09-01\",\n});\nconsole.log(item.status);\n" } ], "x-required-scope": "stock:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/stock/{item_id}/expire": { "post": { "tags": [ "stock" ], "summary": "Expirar item do estoque", "operationId": "expire_stock_item_v1_stock__item_id__expire_post", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockItemStatusResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `stock_item_not_in_stock`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst result = await zemo.stock.expire(\"\");\nconsole.log(result.status); // EXPIRED\n" } ], "x-required-scope": "stock:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/stock/{item_id}/cancel": { "post": { "tags": [ "stock" ], "summary": "Cancelar item do estoque", "operationId": "cancel_stock_item_v1_stock__item_id__cancel_post", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockItemStatusResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `stock_item_cannot_be_cancelled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst result = await zemo.stock.cancel(\"\");\nconsole.log(result.status); // CANCELLED\n" } ], "x-required-scope": "stock:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/stock/simulate-anticipation": { "post": { "tags": [ "stock" ], "summary": "Simular antecipacao do estoque", "description": "Calcula o valor liquido, taxas e descontos de uma antecipacao a partir de itens ja registrados no estoque, **sem criar operacao**. Mesmo calculo do request-anticipation, mas read-only.", "operationId": "simulate_anticipation_from_stock_v1_stock_simulate_anticipation_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateAnticipationFromStock" }, "examples": { "default": { "summary": "Exemplo", "value": { "stock_item_ids": [ "01994c1e-8a10-7000-9000-0000000000a1" ], "requested_advance_value": "10000.00", "fees": { "monthly_rate_pct": 3.5, "floating_days": 2 } } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockSimulationResponse" }, "examples": { "default": { "summary": "Exemplo", "value": { "status": "SIMULATED", "opr_gross_face_value": "10000.00", "opr_net_face_value": "10000.00", "opr_discounted_value": "840.00", "opr_liquid_value": "9160.00", "average_days_in_advance": 70, "floating_days": 2, "receivables": [ { "stock_item_id": "01994c1e-8a10-7000-9000-0000000000a1", "external_id": "NF-2026-001", "gross_face_value": "10000.00", "net_face_value": "10000.00", "requested_advance_value": "10000.00", "due_date": "2026-10-07", "days_advanced": 72, "monthly_rate_pct": "3.5", "discount_brl": "840.00", "liquid_value": "9160.00", "fee_source": "operation" } ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `some_stock_items_not_found`, `mixed_assignor_anticipation`, `total_liquid_value_brl is mutually exclusive with floating_days`, `total_liquid_value_brl exceeds total face value`, `STOCK_ITEM_NFV_NOT_POSITIVE`, `STOCK_ITEM_NFV_ABOVE_GROSS`, `STOCK_ITEM_DISCOUNT_EXCEEDS_BASE`, `STOCK_REQUESTED_VALUE_MISMATCH`, `principal_originator_policy_not_found`, `policy_not_selectable`, `no_policy_resolvable`, `standard_rate_required`, `rate_override_out_of_policy_range`, `floating_days_override_out_of_policy_range`, `discount_override_out_of_policy_range`, `fixed_discount_override_out_of_policy_range`, `liquid_override_requires_policy_band`, `VOCABULARY_CONFLICT`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "examples": { "default": { "summary": "Exemplo", "value": { "detail": { "code": "STOCK_REQUESTED_VALUE_MISMATCH", "message": "requested_advance_value deve ser igual a soma do net_face_value (Net Face Value) dos itens em stock_item_ids: o fluxo de estoque antecipa 100% dos itens selecionados e nao implementa antecipacao parcial. Para antecipar uma fracao do NFV use POST /v1/operations/direct.", "requested_advance_value": "6000.00", "total_net_face_value": "10000.00", "stock_item_count": 1 } } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`, `LIMIT_CONFIG_MISSING`, `LIMIT_ENTITY_CONFIG_MISSING`, `LIMIT_MAX_OPERATION_VALUE`, `LIMIT_AGGREGATE_EXPOSURE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `stock_item_{id}_not_available`, `stock_item_{id}_not_pre_authorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Simular antecipacao de itens ja no estoque (read-only, nao cria nada)\nconst sim = await zemo.stock.simulateAnticipation({\n stockItemIds: [\"\"],\n requestedAdvanceValue: 10000.0,\n fees: { monthlyRatePct: 3.5 },\n});\nconsole.log(sim.oprLiquidValue);\n" }, { "lang": "Python", "label": "SDK Python (zemo)", "source": "import zemo\n\n# Autenticacao de API por Client Credentials\n# (o SDK troca as credenciais por um JWT de curta duracao)\nzemo.user = zemo.Originator(\n client_id=\"zk_test_...\",\n client_secret=\"sk_test_...\",\n environment=\"https://receivables-api-sandbox.zemocapital.com\",\n)\n\n# Simular antecipacao de itens ja no estoque (read-only)\nsim = zemo.Stock.simulate_anticipation(\n stock_item_ids=[\"\"],\n # = soma do net_future_value dos itens (o estoque antecipa sempre 100%)\n requested_net_future_value=10000.00,\n fees=zemo.Fees(monthly_rate_pct=3.5),\n)\nprint(sim.opr_net_present_liquid_value, sim.receivables)\n" } ], "x-required-scope": "simulation:create", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/stock/request-anticipation": { "post": { "tags": [ "stock" ], "summary": "Solicitar antecipacao do estoque", "description": "Selecione itens do estoque e solicite antecipacao. A operacao e criada automaticamente. Status WAITING_APPROVAL se precisa de aprovacao, APPROVED_DIRECT se auto-aprovado.", "operationId": "request_anticipation_from_stock_v1_stock_request_anticipation_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestAnticipationFromStock" }, "examples": { "default": { "summary": "Exemplo", "value": { "stock_item_ids": [ "01994c1e-8a10-7000-9000-0000000000a1" ], "requested_advance_value": "10000.00", "bank": { "use_document_pix": true }, "fees": { "monthly_rate_pct": 3.5, "floating_days": 2 } } } } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationCreateResponse" }, "examples": { "default": { "summary": "Exemplo", "value": { "id": "01994c1e-9b20-7000-9000-0000000000b2", "display_number": "OP-A1B2C3D4-E5F6G7H8", "status": null, "lifecycle_status": "WAITING_APPROVAL", "opr_gross_face_value": "10000.00", "opr_net_face_value": "10000.00", "opr_discounted_value": "840.00", "opr_liquid_value": "9160.00", "opr_net_liquid_value": "9160.00", "other_debt_discounts": "0.00", "average_days_in_advance": 70, "floating_days": 2, "product_id": null, "needs_backoffice_approval": true, "created_at": "2026-07-29T14:30:00Z", "titles": [ { "id": "01994c1e-c000-7000-9000-0000000000a7", "external_id": "NF-2026-001", "backing_type": "NFE", "status": "WAITING_PAYMENT", "requested_advance_value": "10000.00", "liquid_value": "9160.00", "discounted_value": "840.00", "due_date": "2026-10-07", "qty_days_advanced": 72 } ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_required`, `too_many_receivables_max_30`, `some_stock_items_not_found`, `mixed_assignor_anticipation`, `total_liquid_value_brl exceeds total face value`, `CET_OUT_OF_BOUNDS`, `STOCK_ITEM_NFV_NOT_POSITIVE`, `STOCK_ITEM_NFV_ABOVE_GROSS`, `STOCK_ITEM_DISCOUNT_EXCEEDS_BASE`, `STOCK_REQUESTED_VALUE_MISMATCH`, `principal_originator_policy_not_found`, `policy_not_selectable`, `no_policy_resolvable`, `standard_rate_required`, `rate_override_out_of_policy_range`, `floating_days_override_out_of_policy_range`, `discount_override_out_of_policy_range`, `fixed_discount_override_out_of_policy_range`, `liquid_override_requires_policy_band`, `VOCABULARY_CONFLICT`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "examples": { "default": { "summary": "Exemplo", "value": { "detail": { "code": "STOCK_REQUESTED_VALUE_MISMATCH", "message": "requested_advance_value deve ser igual a soma do net_face_value (Net Face Value) dos itens em stock_item_ids: o fluxo de estoque antecipa 100% dos itens selecionados e nao implementa antecipacao parcial. Para antecipar uma fracao do NFV use POST /v1/operations/direct.", "requested_advance_value": "6000.00", "total_net_face_value": "10000.00", "stock_item_count": 1 } } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`, `LIMIT_CONFIG_MISSING`, `LIMIT_ENTITY_CONFIG_MISSING`, `LIMIT_MAX_OPERATION_VALUE`, `LIMIT_AGGREGATE_EXPOSURE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `stock_item_{id}_not_available`, `stock_item_{id}_not_pre_authorized`, `operation_already_open_for_external_id_{external_id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "OBRIGATORIA nesta rota: sem o header a requisicao e recusada com `422` `idempotency_key_required`, antes de qualquer efeito. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Criar operacao real a partir de itens do estoque\nconst op = await zemo.stock.requestAnticipation({\n stockItemIds: [\"\"],\n requestedAdvanceValue: 10000.0,\n bank: { useDocumentPix: true },\n fees: { monthlyRatePct: 3.5 },\n});\nconsole.log(op.id, op.displayNumber);\n" }, { "lang": "Python", "label": "SDK Python (zemo)", "source": "import zemo\n\n# Autenticacao de API por Client Credentials\n# (o SDK troca as credenciais por um JWT de curta duracao)\nzemo.user = zemo.Originator(\n client_id=\"zk_test_...\",\n client_secret=\"sk_test_...\",\n environment=\"https://receivables-api-sandbox.zemocapital.com\",\n)\n\n# Criar operacao a partir de itens do estoque\nop = zemo.Stock.request_anticipation(\n stock_item_ids=[\"\"],\n requested_net_future_value=10000.00,\n bank=zemo.BankData(use_document_pix=True),\n fees=zemo.Fees(monthly_rate_pct=3.5),\n)\nprint(op.id, op.display_number)\n" } ], "x-required-scope": "operation:create", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/simulate": { "post": { "tags": [ "simulation" ], "summary": "Simular antecipacao", "description": "Calcula o valor liquido, taxas e descontos de uma antecipacao **sem criar nada no sistema**. Hierarquia completa de taxas: recebivel > operacao > cedente > sacado > policy originador. Para ativar o nivel do cedente, informe `assignor_document`. O nivel do sacado e resolvido automaticamente via `payer_document` de cada recebivel.", "operationId": "simulate_anticipation_v1_simulate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationRequest" }, "examples": { "default": { "summary": "Exemplo", "value": { "assignor_document": "12345678000195", "receivables": [ { "external_id": "NF-2026-001", "payer_name": "Sacado Sandbox SA", "payer_document": "98765432000198", "gross_face_value": 10000.0, "net_face_value": 10000.0, "requested_advance_value": 10000.0, "due_date": "2026-10-07" } ], "fees": { "monthly_rate_pct": 3.5, "floating_days": 2 } } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationResponse" }, "examples": { "default": { "summary": "Exemplo", "value": { "id": "simulation", "status": "SIMULATED", "opr_gross_face_value": "10000.00", "opr_net_face_value": "10000.00", "opr_discounted_value": "840.00", "opr_liquid_value": "9160.00", "average_days_in_advance": 70, "weighted_avg_days": 70, "fee_hierarchy": "receivable > operation > assignor > payer > policy", "assignor_defaults_used": false, "payer_defaults_used": false, "receivables": [ { "external_id": "NF-2026-001", "identifier": null, "payer_name": "Sacado Sandbox SA", "payer_document": "98765432000198", "requested_advance_value": "10000.00", "net_face_value": "10000.00", "gross_face_value": "10000.00", "due_date": "2026-10-07", "days_advanced": 72, "monthly_rate_pct": "3.5", "discount_pct": "0", "fixed_discount_brl": "0", "floating_days": 2, "discounted_value": "840.00", "liquid_value": "9160.00", "fee_source": "operation" } ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `principal_originator_policy_not_found`, `policy_not_selectable`, `no_policy_resolvable`, `standard_rate_required`, `rate_override_out_of_policy_range`, `floating_days_override_out_of_policy_range`, `discount_override_out_of_policy_range`, `fixed_discount_override_out_of_policy_range`, `liquid_override_requires_policy_band`, `VOCABULARY_CONFLICT`, `DEDUCTIONS_REQUIRED_WITH_GROSS`, `VALUE_DECOMPOSITION_MISMATCH`, `REQUESTED_VALUE_AMBIGUOUS`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "examples": { "default": { "summary": "Exemplo", "value": { "detail": { "code": "validation_error", "message": "1 campo invalido: receivables.0.due_date", "errors": [ { "field": "receivables.0.due_date", "message": "Input should be a valid date", "type": "date_parsing" } ] } } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Simulacao avulsa (read-only, nada e criado)\nconst sim = await zemo.simulations.create({\n receivables: [\n {\n externalId: \"NF-001\",\n payerName: \"Sacado ABC SA\",\n payerDocument: \"98765432000198\",\n netFaceValue: 10000.0,\n requestedAdvanceValue: 10000.0,\n dueDate: \"2026-08-15\",\n },\n ],\n fees: { monthlyRatePct: 3.5 },\n});\nconsole.log(sim.oprLiquidValue);\n" }, { "lang": "Python", "label": "SDK Python (zemo)", "source": "import zemo\n\n# Autenticacao de API por Client Credentials\n# (o SDK troca as credenciais por um JWT de curta duracao)\nzemo.user = zemo.Originator(\n client_id=\"zk_test_...\",\n client_secret=\"sk_test_...\",\n environment=\"https://receivables-api-sandbox.zemocapital.com\",\n)\n\n# Simular antecipacao (read-only, nao cria nada)\nsim = zemo.Simulation.create(\n receivables=[zemo.Receivable(\n external_id=\"NF-001\",\n payer_name=\"Sacado ABC SA\",\n payer_document=\"98765432000198\",\n net_future_value=10000.00,\n requested_net_future_value=10000.00,\n due_date=\"2026-08-15\",\n )],\n fees=zemo.Fees(monthly_rate_pct=3.5),\n)\nprint(sim.opr_net_present_liquid_value)\n" } ], "x-required-scope": "simulation:create", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/products": { "get": { "tags": [ "products" ], "summary": "Listar produtos disponiveis", "description": "Lista os produtos financeiros disponiveis para o originador autenticado (read-only). Um registro por `product_id` — a policy ativa primaria ou mais recente. Use o `product_id` retornado em /simulate, /operations/direct, /stock/simulate-anticipation e /stock/request-anticipation.\n\nFiltros opcionais: `product_type`, `is_primary`. Paginacao: `limit` (1-200, default 50) e `offset`. O campo `total` traz a contagem antes da paginacao.", "operationId": "list_products_v1_products_get", "parameters": [ { "name": "product_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filtra por tipo de produto (match exato)", "title": "Product Type" }, "description": "Filtra por tipo de produto (match exato)" }, { "name": "is_primary", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filtra por produto/policy primaria", "title": "Is Primary" }, "description": "Filtra por produto/policy primaria" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Tamanho da pagina (1-200)", "default": 50, "title": "Limit" }, "description": "Tamanho da pagina (1-200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Deslocamento para paginacao", "default": 0, "title": "Offset" }, "description": "Deslocamento para paginacao" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductsResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst products = await zemo.request(\"GET\", \"/v1/products\");\nconsole.log(products);\n" } ] } }, "/v1/operations": { "get": { "tags": [ "operations" ], "summary": "Listar operacoes", "description": "Retorna operacoes filtradas por status, cedente ou situacao de retorno.", "operationId": "list_operations_v1_operations_get", "parameters": [ { "name": "lifecycle_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lifecycle Status" } }, { "name": "returning_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Returning Status" } }, { "name": "assignor_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Uma pagina:\nconst page = await zemo.operations.page({ status: \"ACTIVE\", limit: 50 });\nconsole.log(page.total);\n\n// Ou itere TODAS as operacoes (paginacao transparente):\nfor await (const op of zemo.operations.query()) {\n console.log(op.id, op.lifecycleStatus);\n}\n" } ], "x-required-scope": "operation:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/operations/{operation_id}": { "get": { "tags": [ "operations" ], "summary": "Obter operacao", "description": "Retorna detalhes da operacao incluindo taxas aplicadas e status.", "operationId": "get_operation_v1_operations__operation_id__get", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Operation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationDetail" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `operation_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst op = await zemo.operations.get(\"\");\nconsole.log(op.lifecycleStatus, op.oprLiquidValue);\n" } ], "x-required-scope": "operation:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/operations/{operation_id}/titles": { "get": { "tags": [ "operations" ], "summary": "Listar titulos da operacao", "description": "Retorna titulos com saldo devedor corrente.", "operationId": "list_operation_titles_v1_operations__operation_id__titles_get", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Operation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TitleListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst titles = await zemo.operations.titles(\"\");\nfor (const title of titles.items) {\n console.log(title.id, title.dueDate, title.currentOutstandingBalanceBrl);\n}\n" } ], "x-required-scope": "operation:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/operations/{operation_id}/cancel": { "post": { "tags": [ "operations" ], "summary": "Cancelar operacao", "description": "Cancela operacao em status WAITING_APPROVAL. Retorna 409 se ja aprovada.", "operationId": "cancel_operation_v1_operations__operation_id__cancel_post", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Operation Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Cancel Operation V1 Operations Operation Id Cancel Post" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `operation_cannot_be_cancelled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst op = await zemo.operations.cancel(\"\");\nconsole.log(op.lifecycleStatus); // CANCELLED\n" } ], "x-required-scope": "operation:cancel", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/operations/direct": { "post": { "tags": [ "operations-direct", "operations-direct" ], "summary": "Criar operacao direta", "description": "Envia cedente, dados bancarios, recebiveis e taxas em uma unica chamada. O sistema registra cedente, sacado e conta automaticamente se nao existirem. A operacao nasce em `APPROVED_DIRECT` quando o total solicitado cabe no limite de auto-aprovacao da policy, e em `WAITING_APPROVAL` caso contrario (inclusive quando nao ha limite configurado).", "operationId": "create_operation_direct_v1_operations_direct_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectOperationCreate" }, "examples": { "default": { "summary": "Exemplo", "value": { "name": "Cedente Sandbox SA", "type": "J", "cnpj": "12345678000195", "email": "financeiro@cedente.com.br", "bank": { "use_document_pix": true }, "receivables": [ { "external_id": "NF-2026-001", "payer_name": "Sacado Sandbox SA", "payer_document": "98765432000198", "gross_face_value": 10000.0, "net_face_value": 10000.0, "requested_advance_value": 10000.0, "due_date": "2026-10-07", "backing_type": "NFE" } ], "fees": { "monthly_rate_pct": 3.5, "floating_days": 2 } } } } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationCreateResponse" }, "examples": { "default": { "summary": "Exemplo", "value": { "id": "01994c1e-9b20-7000-9000-0000000000b2", "display_number": "OP-A1B2C3D4-E5F6G7H8", "status": "WAITING_APPROVAL", "lifecycle_status": null, "opr_gross_face_value": "10000.00", "opr_net_face_value": "10000.00", "opr_discounted_value": "840.00", "opr_liquid_value": "9160.00", "opr_net_liquid_value": "9160.00", "other_debt_discounts": "0.00", "average_days_in_advance": 70, "floating_days": 2, "product_id": null, "needs_backoffice_approval": true, "created_at": null, "titles": [ { "id": "01994c1e-c000-7000-9000-0000000000a7", "external_id": "NF-2026-001", "backing_type": "NFE", "status": "WAITING_PAYMENT", "requested_advance_value": "10000.00", "liquid_value": "9160.00", "discounted_value": "840.00", "due_date": "2026-10-07", "qty_days_advanced": 72, "fee_source": "operation", "monthly_rate_pct": "3.5", "discount_pct": "0", "fixed_discount_brl": "0", "is_partial": false } ], "fee_hierarchy": "receivable > operation > assignor > payer > policy", "has_partial_anticipations": false, "contract_details": { "type": "FULL_CONTRACT", "signature_date": null, "signer_token": null }, "signers_count": 1 } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_required`, `too_many_receivables_max_30`, `signers_required`, `too_many_signers`, `invalid_signer`, `signer_incomplete_for_contract`, `invalid_payer_document`, `invalid_assignor_document`, `total_liquid_value_brl is mutually exclusive with monthly_rate_pct/discount_pct/fixed_discount_brl`, `total_liquid_value_brl exceeds total face value`, `CET_OUT_OF_BOUNDS`, `principal_originator_policy_not_found`, `policy_not_selectable`, `no_policy_resolvable`, `standard_rate_required`, `rate_override_out_of_policy_range`, `floating_days_override_out_of_policy_range`, `discount_override_out_of_policy_range`, `fixed_discount_override_out_of_policy_range`, `liquid_override_requires_policy_band`, `VOCABULARY_CONFLICT`, `DEDUCTIONS_REQUIRED_WITH_GROSS`, `VALUE_DECOMPOSITION_MISMATCH`, `REQUESTED_VALUE_AMBIGUOUS`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "examples": { "default": { "summary": "Exemplo", "value": { "detail": { "code": "idempotency_key_required", "message": "Idempotency-Key header is required for financial operations" } } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`, `LIMIT_CONFIG_MISSING`, `LIMIT_ENTITY_CONFIG_MISSING`, `LIMIT_MAX_OPERATION_VALUE`, `LIMIT_AGGREGATE_EXPOSURE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `assignor_document_archived`, `stock_item_{id}_not_available`, `stock_consumed_concurrently`, `operation_already_open_for_external_id_{external_id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "OBRIGATORIA nesta rota: sem o header a requisicao e recusada com `422` `idempotency_key_required`, antes de qualquer efeito. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Criar operacao em uma unica chamada (registra cedente/sacado/banco)\nconst op = await zemo.operations.createDirect({\n name: \"Cedente XPTO SA\",\n type: \"J\", // \"F\" (CPF) ou \"J\" (CNPJ)\n cnpj: \"12345678000195\",\n email: \"financeiro@xpto.com\",\n bank: { useDocumentPix: true },\n receivables: [\n {\n externalId: \"NF-001\",\n payerName: \"Sacado ABC SA\",\n payerDocument: \"98765432000198\",\n netFaceValue: 10000.0,\n requestedAdvanceValue: 10000.0,\n dueDate: \"2026-08-15\",\n },\n ],\n fees: { monthlyRatePct: 3.5 },\n});\nconsole.log(op.id, op.displayNumber);\n" }, { "lang": "Python", "label": "SDK Python (zemo)", "source": "import zemo\n\n# Autenticacao de API por Client Credentials\n# (o SDK troca as credenciais por um JWT de curta duracao)\nzemo.user = zemo.Originator(\n client_id=\"zk_test_...\",\n client_secret=\"sk_test_...\",\n environment=\"https://receivables-api-sandbox.zemocapital.com\",\n)\n\n# Criar operacao em uma unica chamada (registra cedente/sacado/banco)\nop = zemo.Operation.create_direct(\n name=\"Cedente XPTO SA\",\n type=\"J\", # \"F\" (CPF) ou \"J\" (CNPJ)\n cnpj=\"12345678000195\",\n email=\"financeiro@xpto.com\",\n bank=zemo.BankData(use_document_pix=True),\n receivables=[zemo.Receivable(\n external_id=\"NF-001\",\n payer_name=\"Sacado ABC SA\",\n payer_document=\"98765432000198\",\n net_future_value=10000.00,\n # Antecipacao PARCIAL: use requested_net_future_value_percent=60\n # (percentual do NFV) OU o valor absoluto — nunca os dois.\n requested_net_future_value=10000.00,\n due_date=\"2026-08-15\",\n )],\n fees=zemo.Fees(monthly_rate_pct=3.5),\n)\nprint(op.id, op.display_number)\n" } ], "x-required-scope": "operation:create", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/operations/{operation_id}/contract/send-for-signature": { "post": { "tags": [ "operations" ], "summary": "Enviar contrato para assinatura", "description": "Dispara o contrato da operacao para assinatura e devolve a `sign_url` de cada signatario.\n\nEm geral voce **nao precisa chamar esta rota**: operacoes criadas pela API disparam o contrato automaticamente assim que sao aprovadas. Ela existe para (a) o modo **embedded**, quando voce quer apresentar o link de assinatura na sua propria interface em vez de deixar o e-mail automatico sair, e (b) re-disparo apos falha.\n\nPor isso o scope e **`contract:send`**, separado do `contract:read` do acompanhamento: ele e um **opt-in de borda**, nao faz parte do recorte tipico. Peca-o so na credencial que realmente dispara contrato.\n\nSe o contrato ja foi despachado, responde `409 contract_already_exists` — use `GET /v1/operations/{operation_id}/contract/signers` para obter as URLs do despacho vigente.", "operationId": "send_operation_contract_for_signature_v1_operations__operation_id__contract_send_for_signature_post", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Operation Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendContractForOperationEmbeddedRequest", "default": {} } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSendResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`, `too_many_signers`, `signer_snapshot_incomplete`, `template_id_or_contract_pdf_url_required`, `template_id_must_be_uuid`, `CONTRACT_TITLE_REQUESTED_ABOVE_NFV`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `operation_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `contract_already_exists`, `operation_not_in_signable_state`, `operation_state_changed_during_dispatch`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "502": { "description": "Falha no provedor externo. O provedor externo de assinatura falhou ou nao respondeu. Nenhum documento parcial fica vivo: o despacho contem a falha (o documento e removido no provedor) e a operacao fica re-disparavel. `detail` e uma string com o codigo. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `zapsign_create_failed`, `zapsign_add_signer_failed`, `zapsign_update_signer_failed`, `zapsign_template_inventory_failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo, ConflictError } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Voce normalmente NAO precisa chamar isto: a operacao dispara o contrato\n// sozinha ao ser aprovada. Use para o modo EMBEDDED (apresentar o link de\n// assinatura na sua propria interface, sem o e-mail automatico).\n// Ja despachado? A chamada responde 409 — leia as URLs do despacho vigente\n// com operations.contractSigners().\nconst operationId = \"\";\nlet signers: Array<{ name?: string | null; signUrl?: string | null }>;\ntry {\n const dispatch = await zemo.operations.sendContractForSignature(operationId, {\n embedded: true,\n });\n signers = dispatch.signers.map((s) => ({ name: s.name, signUrl: s.signUrl }));\n} catch (err) {\n if (!(err instanceof ConflictError)) throw err;\n // Os DOIS 409 desta rota tem recuperacao OPOSTA — ramifique pelo code:\n if (err.code === \"contract_already_exists\") {\n // Ja despachado (em geral pelo envio automatico): nao e falha.\n const contract = await zemo.operations.contractSigners(operationId);\n signers = contract.signers.map((s) => ({ name: s.name, signUrl: s.signUrl }));\n } else {\n // operation_not_in_signable_state: a operacao ainda NAO foi aprovada.\n // Nao re-tente em loop — aguarde o webhook operation.approved.\n throw err;\n }\n}\n\n// signUrl e CREDENCIAL: quem tem a URL assina o documento.\n// NUNCA registre em log e NUNCA guarde em claro — entregue `signers` direto\n// a tela que o signatario vai usar.\n" } ], "x-required-scope": "contract:send", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/operations/{operation_id}/contract/signers": { "get": { "tags": [ "operations" ], "summary": "Consultar signatarios do contrato", "description": "Le AO VIVO no provedor de assinatura os signatarios do contrato da operacao, com o `status` de cada um e a `sign_url` para assinar. E a fonte a usar sempre que voce precisar da URL de assinatura e nao a tiver em maos — inclusive no replay de idempotencia do disparo, em que a `sign_url` volta `null` por redacao deliberada do cache.\n\nExige apenas **`contract:read`**: como o disparo e automatico na aprovacao, acompanhar a assinatura e o caso TIPICO e nao precisa vir acompanhado do poder de disparar (`contract:send`).", "operationId": "get_operation_contract_signers_v1_operations__operation_id__contract_signers_get", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Operation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSignersResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `contract_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `contract_not_dispatched`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "502": { "description": "Falha no provedor externo. O provedor externo de assinatura falhou ou nao respondeu. Nenhum documento parcial fica vivo: o despacho contem a falha (o documento e removido no provedor) e a operacao fica re-disparavel. `detail` e uma string com o codigo. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `zapsign_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Leitura AO VIVO no provedor — use sempre que precisar da URL de\n// assinatura e nao a tiver em maos (inclusive no replay de idempotencia,\n// em que signUrl volta null por redacao deliberada do cache).\nconst contract = await zemo.operations.contractSigners(\"\");\nconsole.log(contract.documentStatus);\n\n// Use `signed` (booleano) para o progresso na sua tela; `status` e texto\n// do provedor e pode mudar sem aviso.\n// signUrl e CREDENCIAL: entregue a tela, nunca ao log.\nconst pendentes = contract.signers\n .filter((s) => !s.signed)\n .map((s) => ({ name: s.name, signUrl: s.signUrl }));\n" } ], "x-required-scope": "contract:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/payers": { "get": { "tags": [ "payers" ], "summary": "Listar sacados", "description": "Retorna sacados cadastrados do originador.", "operationId": "list_payers_v1_payers_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Uma pagina:\nconst page = await zemo.payers.page({ limit: 50 });\nconsole.log(page.total);\n\n// Ou itere TODOS os sacados (paginacao transparente):\nfor await (const payer of zemo.payers.query()) {\n console.log(payer.id, payer.legalName);\n}\n" } ], "x-required-scope": "payer:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "post": { "tags": [ "payers" ], "summary": "Cadastrar sacado", "description": "Registra um novo sacado vinculado ao originador. Aceita CPF (11 digitos) ou CNPJ (14 digitos) no campo `cnpj`, com validacao de digito verificador. Dedup por documento normalizado: se o sacado ja existe, retorna o existente (200); se estava arquivado, reativa com os dados enviados (200).", "operationId": "create_payer_v1_payers_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerCreateResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst payer = await zemo.payers.create({\n cnpj: \"98765432000198\",\n legalName: \"Sacado ABC SA\",\n email: \"contas@sacadoabc.com\",\n});\nconsole.log(payer.id);\n" } ], "x-required-scope": "payer:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/payers/{payer_id}": { "get": { "tags": [ "payers" ], "summary": "Obter sacado", "description": "Retorna detalhes do sacado incluindo endereco e configuracoes.", "operationId": "get_payer_v1_payers__payer_id__get", "parameters": [ { "name": "payer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payer Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerDetail" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `payer_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst payer = await zemo.payers.get(\"\");\nconsole.log(payer.legalName);\n" } ], "x-required-scope": "payer:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "patch": { "tags": [ "payers" ], "summary": "Atualizar sacado", "description": "Atualiza campos do sacado. Envia apenas os campos que deseja alterar.", "operationId": "update_payer_v1_payers__payer_id__patch", "parameters": [ { "name": "payer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payer Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerUpdateResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `no_fields_to_update`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `payer_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst payer = await zemo.payers.update(\"\", {\n email: \"novo@sacadoabc.com\",\n});\nconsole.log(payer.email);\n" } ], "x-required-scope": "payer:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "delete": { "tags": [ "payers" ], "summary": "Arquivar sacado", "operationId": "archive_payer_v1_payers__payer_id__delete", "parameters": [ { "name": "payer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payer Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `payer_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Soft-delete (arquiva o sacado)\nawait zemo.payers.delete(\"\");\n" } ], "x-required-scope": "payer:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/assignors": { "get": { "tags": [ "assignors" ], "summary": "Listar cedentes", "description": "Retorna cedentes cadastrados, filtrados opcionalmente por sacado.", "operationId": "list_assignors_v1_assignors_get", "parameters": [ { "name": "payer_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payer Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignorListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Uma pagina:\nconst page = await zemo.assignors.page({ limit: 50 });\nconsole.log(page.total);\n\n// Ou itere TODOS os cedentes (paginacao transparente):\nfor await (const assignor of zemo.assignors.query()) {\n console.log(assignor.id, assignor.legalName);\n}\n" } ], "x-required-scope": "assignor:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "post": { "tags": [ "assignors" ], "summary": "Cadastrar cedente", "description": "Registra um novo cedente vinculado ao originador. Dedup por document: se CNPJ/CPF ja existe, retorna 200.", "operationId": "create_assignor_v1_assignors_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignorCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Create Assignor V1 Assignors Post" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `payer_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `assignor_document_archived`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Dedup por document: se o CPF/CNPJ ja existe, retorna o cedente existente\nconst assignor = await zemo.assignors.create({\n document: \"12345678000195\",\n legalName: \"Cedente XPTO SA\",\n type: \"J\", // \"F\" (CPF) ou \"J\" (CNPJ)\n email: \"financeiro@xpto.com\",\n});\nconsole.log(assignor.id);\n" } ], "x-required-scope": "assignor:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/assignors/{assignor_id}": { "get": { "tags": [ "assignors" ], "summary": "Obter cedente", "description": "Retorna detalhes do cedente incluindo dados de contato e conta bancaria.", "operationId": "get_assignor_v1_assignors__assignor_id__get", "parameters": [ { "name": "assignor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Assignor Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignorDetail" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `assignor_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst assignor = await zemo.assignors.get(\"\");\nconsole.log(assignor.legalName, assignor.email);\n" } ], "x-required-scope": "assignor:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "patch": { "tags": [ "assignors" ], "summary": "Atualizar cedente", "description": "Atualiza campos do cedente. Envia apenas os campos que deseja alterar.", "operationId": "update_assignor_v1_assignors__assignor_id__patch", "parameters": [ { "name": "assignor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Assignor Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignorUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Assignor V1 Assignors Assignor Id Patch" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `no_fields_to_update`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `assignor_not_found`, `payer_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst assignor = await zemo.assignors.update(\"\", {\n email: \"novo@xpto.com\",\n phone: \"+5511999990000\",\n});\nconsole.log(assignor.email);\n" } ], "x-required-scope": "assignor:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/assignors/{assignor_id}/outstanding-balance": { "get": { "tags": [ "assignors" ], "summary": "Saldo em aberto do cedente", "description": "Retorna o saldo devedor total do cedente, separado em atrasado e a vencer. Inclui detalhes dos titulos em atraso.", "operationId": "get_assignor_outstanding_balance_v1_assignors__assignor_id__outstanding_balance_get", "parameters": [ { "name": "assignor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Assignor Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Assignor Outstanding Balance V1 Assignors Assignor Id Outstanding Balance Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `assignor_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Saldo devedor do cedente: atrasado + a vencer\nconst balance = await zemo.assignors.outstandingBalance(\"\");\nconsole.log(balance.totalOutstandingBrl, balance.overdueBalanceBrl);\n" } ], "x-required-scope": "assignor:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/bank-accounts": { "get": { "tags": [ "bank-accounts" ], "summary": "List Bank Accounts", "description": "List bank accounts for assignors belonging to this originator.", "operationId": "list_bank_accounts_v1_bank_accounts_get", "parameters": [ { "name": "owner_assignor_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Assignor Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Bank Accounts V1 Bank Accounts Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Read-only: contas criadas automaticamente via operacoes\nconst accounts = await zemo.bankAccounts.query({\n ownerAssignorId: \"\",\n});\nfor (const account of accounts) {\n console.log(account.bankCode, account.pixKey, account.isPrimary);\n}\n" } ], "x-required-scope": "bank-account:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/titles": { "get": { "tags": [ "titles" ], "summary": "List Titles", "operationId": "list_titles_v1_titles_get", "parameters": [ { "name": "operation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operation Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "payer_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payer Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TitleListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Uma pagina:\nconst page = await zemo.titles.page({ status: \"OPEN\", limit: 50 });\nconsole.log(page.total);\n\n// Ou itere TODOS os titulos (paginacao transparente):\nfor await (const title of zemo.titles.query({ status: \"OPEN\" })) {\n console.log(title.id, title.currentOutstandingBalanceBrl);\n}\n" } ], "x-required-scope": "title:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/titles/{title_id}": { "get": { "tags": [ "titles" ], "summary": "Get Title", "operationId": "get_title_v1_titles__title_id__get", "parameters": [ { "name": "title_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Title Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TitleDetail" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `title_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst title = await zemo.titles.get(\"\");\nconsole.log(title.status, title.currentOutstandingBalanceBrl);\n" } ], "x-required-scope": "title:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/titles/{title_id}/balance-events": { "get": { "tags": [ "titles" ], "summary": "List Balance Events", "operationId": "list_balance_events_v1_titles__title_id__balance_events_get", "parameters": [ { "name": "title_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Title Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceEventListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Ledger completo do titulo (juros, pagamentos, descontos)\nconst events = await zemo.titles.balanceEvents(\"\");\nfor (const event of events) {\n console.log(event.eventType, event.amountBrl, event.outstandingAfterBrl);\n}\n" } ], "x-required-scope": "title:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/assignor-payables": { "get": { "tags": [ "assignor-payables" ], "summary": "List Payables", "operationId": "list_payables_v1_assignor_payables_get", "parameters": [ { "name": "assignor_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Payables V1 Assignor Payables Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst payables = await zemo.request(\"GET\", \"/v1/assignor-payables\", {\n params: { assignorId: \"\", status: \"OPEN\", limit: 50 },\n});\nconsole.log(payables);\n" } ], "x-required-scope": "payable:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "post": { "tags": [ "assignor-payables" ], "summary": "Create Payable", "operationId": "create_payable_v1_assignor_payables_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayableCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Create Payable V1 Assignor Payables Post" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `assignor_not_found`, `payer_not_found`, `operation_not_found`, `title_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst payable = await zemo.request(\"POST\", \"/v1/assignor-payables\", {\n body: {\n assignorId: \"\",\n kind: \"RECOURSE\",\n amountBrl: 1500.0,\n reason: \"Recompra de titulo vencido\",\n },\n});\nconsole.log(payable);\n" } ], "x-required-scope": "payable:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/assignor-payables/{payable_id}": { "get": { "tags": [ "assignor-payables" ], "summary": "Get Payable", "operationId": "get_payable_v1_assignor_payables__payable_id__get", "parameters": [ { "name": "payable_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payable Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Payable V1 Assignor Payables Payable Id Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `payable_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst payable = await zemo.request(\n \"GET\",\n \"/v1/assignor-payables/\",\n);\nconsole.log(payable);\n" } ], "x-required-scope": "payable:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/assignor-payables/{payable_id}/payments": { "get": { "tags": [ "assignor-payables" ], "summary": "List Payable Payments", "operationId": "list_payable_payments_v1_assignor_payables__payable_id__payments_get", "parameters": [ { "name": "payable_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payable Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Payable Payments V1 Assignor Payables Payable Id Payments Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst payments = await zemo.request(\n \"GET\",\n \"/v1/assignor-payables//payments\",\n);\nconsole.log(payments);\n" } ], "x-required-scope": "payable:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "post": { "tags": [ "assignor-payables" ], "summary": "Registrar pagamento de um payable", "description": "Registra um pagamento contra o payable e abate `remaining_amount_brl`.\n\n**Dedup opcional:** envie `external_id` com o identificador do pagamento no seu sistema e um retry com o MESMO `external_id` devolve o pagamento original (`idempotent_replay: true`) em vez de registrar um segundo debito. Sem `external_id` o comportamento e o de sempre — dois POSTs iguais registram dois pagamentos, que e o correto para dois pagamentos parciais legitimos de mesmo valor.\n\nO replay vale inclusive para o retry do pagamento que LIQUIDOU o payable. **Excecao do `external_id`:** apos um write-off o dedup por `external_id` responde `409 payable_already_settled` em vez de replayar, porque a divida foi resolvida por decisao contabil e nao ha saldo a devolver. Isso nao afeta o `Idempotency-Key`: se a chamada original enviou o header, o retry com a mesma chave dentro do TTL continua devolvendo a resposta original, como especificado para o header.", "operationId": "record_payable_payment_v1_assignor_payables__payable_id__payments_post", "parameters": [ { "name": "payable_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payable Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayablePaymentRecord" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Record Payable Payment V1 Assignor Payables Payable Id Payments Post" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `payable_not_found`, `capital_inflow_not_found`, `operation_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `payable_already_settled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst payment = await zemo.request(\n \"POST\",\n \"/v1/assignor-payables//payments\",\n {\n body: {\n source: \"PIX\",\n paidAmountBrl: 1500.0,\n },\n },\n);\nconsole.log(payment);\n" } ], "x-required-scope": "payable:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/assignor-payables/{payable_id}/write-off": { "post": { "tags": [ "assignor-payables" ], "summary": "Write Off Payable", "operationId": "write_off_payable_v1_assignor_payables__payable_id__write_off_post", "parameters": [ { "name": "payable_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payable Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Write Off Payable V1 Assignor Payables Payable Id Write Off Post" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`, `payable_cannot_be_written_off`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst result = await zemo.request(\n \"POST\",\n \"/v1/assignor-payables//write-off\",\n);\nconsole.log(result);\n" } ], "x-required-scope": "payable:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/discount-credits": { "get": { "tags": [ "discount-credits" ], "summary": "List Discount Credits", "operationId": "list_discount_credits_v1_discount_credits_get", "parameters": [ { "name": "assignor_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" } }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Active Only" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Discount Credits V1 Discount Credits Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst credits = await zemo.request(\"GET\", \"/v1/discount-credits\", {\n params: { assignorId: \"\", activeOnly: true },\n});\nconsole.log(credits);\n" } ], "x-required-scope": "discount-credit:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "post": { "tags": [ "discount-credits" ], "summary": "Criar credito de desconto", "description": "Cria um credito de desconto para o cedente (consumido por FIFO nas operacoes seguintes).\n\n**Dedup opcional:** envie `external_id` com o identificador do credito no seu sistema e um retry com o MESMO `external_id` devolve o credito original (`idempotent_replay: true`) em vez de criar um segundo. Sem `external_id` o comportamento e o de sempre.", "operationId": "create_discount_credit_v1_discount_credits_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountCreditCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Create Discount Credit V1 Discount Credits Post" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `assignor_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst credit = await zemo.request(\"POST\", \"/v1/discount-credits\", {\n body: {\n assignorId: \"\",\n sourceKind: \"MANUAL\",\n originalAmountBrl: 250.0,\n reason: \"Credito comercial concedido\",\n },\n});\nconsole.log(credit);\n" } ], "x-required-scope": "discount-credit:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/discount-credits/{credit_id}/consumptions": { "get": { "tags": [ "discount-credits" ], "summary": "List Credit Consumptions", "operationId": "list_credit_consumptions_v1_discount_credits__credit_id__consumptions_get", "parameters": [ { "name": "credit_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Credit Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Credit Consumptions V1 Discount Credits Credit Id Consumptions Get" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst consumptions = await zemo.request(\n \"GET\",\n \"/v1/discount-credits//consumptions\",\n);\nconsole.log(consumptions);\n" } ], "x-required-scope": "discount-credit:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/webhooks": { "get": { "tags": [ "webhooks" ], "summary": "Listar webhooks", "description": "Retorna webhooks cadastrados pelo originador.", "operationId": "list_webhooks_v1_webhooks_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Uma pagina:\nconst page = await zemo.webhooks.page();\nconsole.log(page.total);\n\n// Ou itere TODAS as inscricoes:\nfor await (const webhook of zemo.webhooks.list()) {\n console.log(webhook.id, webhook.url);\n}\n" } ], "x-required-scope": "webhook:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "post": { "tags": [ "webhooks" ], "summary": "Registrar webhook", "description": "Cadastra um webhook para receber notificacoes. O hmac_secret e exibido apenas nesta resposta.", "operationId": "create_webhook_v1_webhooks_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" }, "examples": { "default": { "summary": "Exemplo", "value": { "url": "https://api.seu-dominio.com.br/zemo/webhooks", "events": [ "operation.approved", "operation.paid", "title.paid" ], "description": "Integracao principal" } } } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateResponse" }, "examples": { "default": { "summary": "Exemplo", "value": { "id": "01994c1e-3c00-7000-9000-000000000003", "url": "https://api.seu-dominio.com.br/zemo/webhooks", "event_types": [ "operation.approved", "operation.paid", "title.paid" ], "hmac_secret": "whsec_", "created_at": "2026-07-29T14:30:00Z" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `webhook_requires_originator_id`, `webhook_event_type_unknown`, `webhook_event_type_not_emitted`, `webhook_limit_reached`, `url_* (url_scheme_not_https, url_port_not_allowed, url_host_not_fqdn, ...)`, `ip_* (ip_private, ip_loopback, ip_not_global, ...)`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" }, "examples": { "default": { "summary": "Exemplo", "value": { "detail": { "code": "url_scheme_not_https", "message": "webhook url rejected: url_scheme_not_https" } } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nconst webhook = await zemo.webhooks.create({\n url: \"https://suaempresa.com/webhooks/zemo\",\n events: [\"operation.approved\", \"title.paid\"],\n});\n// O hmacSecret e retornado UMA UNICA VEZ - persista com seguranca:\nconsole.log(webhook.id, webhook.hmacSecret);\n\n// No seu handler HTTP, valide a assinatura sem rede:\n// const event = zemo.webhooks.parse({ payload: rawBody, signature, secret });\n" } ], "x-required-scope": "webhook:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/webhooks/{webhook_id}": { "patch": { "tags": [ "webhooks" ], "summary": "Atualizar webhook", "description": "Atualiza url, eventos, descricao ou o estado ativo de um webhook. Campos ausentes ficam inalterados. Nao rotaciona o segredo.", "operationId": "update_webhook_v1_webhooks__webhook_id__patch", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSummary" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `webhook_update_empty`, `webhook_event_type_unknown`, `webhook_event_type_not_emitted`, `url_* (url_scheme_not_https, url_port_not_allowed, url_host_not_fqdn, ...)`, `ip_* (ip_private, ip_loopback, ip_not_global, ...)`.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `not_found`, `webhook_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Atualizar uma inscricao: url, eventos, descricao ou o estado ativo.\n// Campos ausentes ficam inalterados; o segredo NAO e rotacionado.\n// Sem wrapper dedicado ainda -> escape hatch tipado zemo.request().\nconst webhook = await zemo.request(\n \"PATCH\",\n \"/v1/webhooks/\",\n {\n body: {\n events: [\"operation.approved\", \"title.paid\"],\n active: false,\n },\n },\n);\nconsole.log(webhook);\n" } ], "x-required-scope": "webhook:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] }, "delete": { "tags": [ "webhooks" ], "summary": "Arquivar webhook", "operationId": "archive_webhook_v1_webhooks__webhook_id__delete", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "OPCIONAL nesta rota — mas HONRADA se enviada: o middleware aplica a mesma deduplicacao das rotas financeiras. Sem o header nao ha protecao alguma contra reenvio. Chave de idempotencia da requisicao, no escopo do originador autenticado. DEVE ter entre 16 e 80 caracteres (UUID recomendado); fora dessa faixa a requisicao e recusada com `422 idempotency_key_invalid` ANTES de qualquer efeito. Reenvio com a MESMA chave e o MESMO corpo devolve a resposta guardada da primeira execucao, sem executar de novo, com o header `Idempotency-Replayed: true`; a MESMA chave com corpo diferente responde `409 idempotency_key_reused_with_different_body`, e em ROTA diferente responde `409 idempotency_key_reused_on_different_route`. Se a primeira chamada ainda estiver em andamento, o retry recebe `409 idempotency_key_in_flight` (nunca uma segunda execucao). Reutilize a mesma chave em TODOS os retries de uma mesma operacao. Se o processo que detem a execucao morrer sem liberar a chave, ela pode responder `409 idempotency_key_in_flight` por ATE 600 segundos — esse valor e um TETO, nao uma duracao garantida (pode ser encurtado sem aviso; alargar exigiria versao nova): passado o teto a reserva expira sozinha e o retry seguinte volta a executar normalmente. Ha ainda um `503 idempotency_unavailable`, declarado por antecipacao: significa que o controle de idempotencia esta indisponivel e a requisicao NAO foi executada — retente com a MESMA chave. Ele NAO ocorre na configuracao vigente (o modo fail-closed esta desligado); esta no contrato para que liga-lo no futuro nao seja uma mudanca incompativel.", "schema": { "type": "string", "minLength": 16, "maxLength": 80 } } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.\n\nCodigos possiveis nesta operacao: `idempotency_key_invalid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "404": { "description": "Recurso nao encontrado. Recurso inexistente ou fora do escopo do originador. `detail` e uma string.\n\nCodigos possiveis nesta operacao: `webhook_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "409": { "description": "Conflito de estado. O estado atual do recurso nao permite a operacao. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `idempotency_key_reused_with_different_body`, `idempotency_key_reused_on_different_route`, `idempotency_key_in_flight`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } }, "503": { "description": "Servico temporariamente indisponivel. Dependencia indisponivel. Re-tentavel com backoff.\n\nCodigos possiveis nesta operacao: `idempotency_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\nawait zemo.webhooks.delete(\"\");\n" } ], "x-required-scope": "webhook:write", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } }, "/v1/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "webhooks" ], "summary": "Listar entregas do webhook", "description": "Retorna historico de entregas (tentativas) de um webhook.", "operationId": "list_deliveries_v1_webhooks__webhook_id__deliveries_get", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "422": { "description": "Requisicao invalida. Falha de SCHEMA ou violacao de REGRA DE NEGOCIO — a API usa 422 para as duas coisas, e `detail` assume tres formas (ver `HTTPValidationError`): objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra estruturada) ou string com o codigo da regra. Varias strings de regra levam um sufixo `: ` variavel (ids, campos, faixas) — classifique por PREFIXO ate o `:`, nunca por igualdade da string inteira.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Nao autenticado. Credencial ausente, invalida ou expirada. `detail` e uma string com o codigo.\n\nCodigos possiveis nesta operacao: `not_authenticated`, `token_expired`, `invalid_token`, `invalid_token_type`, `user_not_found`, `missing_client_credentials`, `invalid_client_credentials`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "403": { "description": "Acesso negado. A credencial e valida mas nao pode executar a operacao (scope insuficiente ou limite de politica). `detail` e um objeto com `code`.\n\nCodigos possiveis nesta operacao: `scope_insufficient`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "429": { "description": "Limite de requisicoes excedido. Teto de requisicoes por minuto excedido. O header `Retry-After` traz os segundos a aguardar. Ha DOIS limites e os dois valem — o de ORIGEM (por IP) e o de TOKEN (por credencial) — mas o corpo e UM SO: `detail` e sempre um objeto com `code`, `scope` (`ip` ou `token`), `limit_rpm`, `retry_after_seconds` e `message`. Quem negou se le em `detail.scope`.\n\nCodigos possiveis nesta operacao: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/headers/XZemoEnv" }, "X-Zemo-API-Version": { "$ref": "#/components/headers/XZemoAPIVersion" } } } }, "x-codeSamples": [ { "lang": "TypeScript", "label": "SDK Node (@zemocapital/sdk)", "source": "import { Zemo } from \"@zemocapital/sdk\";\n\n// zk_test_* -> sandbox | zk_live_* -> producao (ambiente inferido da credencial)\nconst zemo = new Zemo({\n clientId: process.env.ZEMO_CLIENT_ID!,\n clientSecret: process.env.ZEMO_CLIENT_SECRET!,\n});\n\n// Auditoria de entregas (status, tentativas, response codes)\nconst deliveries = await zemo.webhooks.deliveries(\"\");\nfor (const delivery of deliveries.items) {\n console.log(delivery.eventType, delivery.status, delivery.attempts);\n}\n" } ], "x-required-scope": "webhook:read", "security": [ { "BearerJWT": [] }, { "ClientId": [], "ClientSecret": [] } ] } } }, "components": { "schemas": { "Address": { "properties": { "zip_code": { "type": "string", "title": "Zip Code", "description": "CEP (8 digitos)" }, "street": { "type": "string", "title": "Street", "description": "Logradouro" }, "number": { "type": "string", "title": "Number", "description": "Numero" }, "complement": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Complement" }, "neighborhood": { "type": "string", "title": "Neighborhood", "description": "Bairro" }, "city": { "type": "string", "title": "City", "description": "Cidade" }, "state": { "type": "string", "title": "State", "description": "UF (2 letras)" }, "country": { "type": "string", "title": "Country", "default": "Brasil" } }, "type": "object", "required": [ "zip_code", "street", "number", "neighborhood", "city", "state" ], "title": "Address" }, "AssignorCreate": { "properties": { "document": { "type": "string", "maxLength": 18, "minLength": 11, "title": "Document", "description": "CPF (11 digitos) ou CNPJ (14 digitos). Aceita pontuacao (ex: 12.345.678/0001-95) — e NORMALIZADO para apenas digitos e tem o DV validado; documento invalido retorna 422. Gravado NORMALIZADO em document_number/document_hash (premissa do auto-match do escrow)." }, "legal_name": { "type": "string", "maxLength": 150, "minLength": 2, "title": "Legal Name", "description": "Razao social do cedente" }, "type": { "type": "string", "title": "Type", "description": "Tipo de pessoa: `J` (juridica) ou `F` (fisica). Comparacao SENSIVEL a caixa: o cadastro grava `LEGAL_ENTITY` somente quando o valor e exatamente `J`; QUALQUER outro valor (inclusive `j`) grava `NATURAL_PERSON`.", "default": "J" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Email do cedente" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone", "description": "Telefone" }, "trade_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trade Name", "description": "Nome fantasia" }, "payer_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Payer Id", "description": "ID do sacado vinculado (opcional)" } }, "type": "object", "required": [ "document", "legal_name" ], "title": "AssignorCreate" }, "AssignorDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "payer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payer Id" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/AssignorType" }, { "type": "null" } ], "title": "Type" }, "document_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Hash" }, "trade_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trade Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "transfer_method": { "anyOf": [ { "$ref": "#/components/schemas/TransferMethod" }, { "type": "null" } ], "title": "Transfer Method" }, "data_confirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Data Confirmed" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "originator_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Originator Id" }, "primary_bank_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Bank Account Id" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "legal_name" ], "title": "AssignorDetail" }, "AssignorListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AssignorSummary" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "items", "total" ], "title": "AssignorListResponse" }, "AssignorSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "payer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payer Id" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/AssignorType" }, { "type": "null" } ], "title": "Type" }, "document_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Hash" }, "trade_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trade Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "transfer_method": { "anyOf": [ { "$ref": "#/components/schemas/TransferMethod" }, { "type": "null" } ], "title": "Transfer Method" }, "data_confirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Data Confirmed" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "legal_name" ], "title": "AssignorSummary" }, "AssignorUpdate": { "properties": { "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "trade_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trade Name" }, "payer_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Payer Id", "description": "Vincular sacado ao cedente" } }, "type": "object", "title": "AssignorUpdate" }, "BalanceEvent": { "properties": { "id": { "type": "string", "title": "Id" }, "event_type": { "title": "Event Type", "$ref": "#/components/schemas/BalanceEventType" }, "event_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Event At" }, "effective_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Effective At" }, "payment_delta_brl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Delta Brl" }, "interest_delta_brl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interest Delta Brl" }, "late_fee_delta_brl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Late Fee Delta Brl" }, "outstanding_before_brl": { "type": "string", "title": "Outstanding Before Brl" }, "outstanding_after_brl": { "type": "string", "title": "Outstanding After Brl" }, "triggered_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Triggered By" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "type": "object", "required": [ "id", "event_type", "outstanding_before_brl", "outstanding_after_brl" ], "title": "BalanceEvent" }, "BalanceEventListResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/BalanceEvent" }, "type": "array", "title": "Events" } }, "type": "object", "required": [ "events" ], "title": "BalanceEventListResponse" }, "BankData": { "properties": { "use_document_pix": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Document Pix", "description": "Pagamento via PIX em chave PIX do CPF/CNPJ, com CPF (type=F) ou CNPJ (type=J) do cedente." }, "code": { "anyOf": [ { "type": "string", "maxLength": 3, "minLength": 1 }, { "type": "null" } ], "title": "Code", "description": "Codigo COMPE do banco: EXATAMENTE 3 digitos (ex.: `341` Itau, `001` Banco do Brasil). Obrigatorio para conta bancaria. ISPB de 8 digitos NAO e aceito aqui — a conversao COMPE->ISPB e feita internamente, em memoria, no momento do pagamento.", "examples": [ "341" ] }, "agency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency", "description": "Agencia. Obrigatorio para conta bancaria.", "examples": [ "1234" ] }, "account": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account", "description": "Numero da conta com digito. Obrigatorio para conta bancaria.", "examples": [ "56789-0" ] }, "type": { "type": "string", "title": "Type", "description": "Tipo da conta: `CC` (corrente), `CP` (poupanca) ou `SA` (salario). NAO validado hoje — outro valor e aceito e gravado como veio.", "default": "CC", "examples": [ "CC" ] } }, "type": "object", "title": "BankData" }, "ContractDispatchSigner": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Nome do signatario." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Status do signatario no provedor no momento do despacho." }, "sign_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sign Url", "description": "URL de assinatura do signatario — trate como CREDENCIAL: quem tem a URL assina. NAO a persista em claro nem a envie a canal nao confiavel. Vem `null` no REPLAY de idempotencia (a redacao do cache e deliberada): nesse caso use `GET /v1/operations/{operation_id}/contract/signers`." } }, "type": "object", "title": "ContractDispatchSigner", "description": "Signatario como ele saiu do DESPACHO (create + add_signer)." }, "ContractSendResponse": { "properties": { "operation_id": { "type": "string", "title": "Operation Id" }, "contract_id": { "type": "string", "title": "Contract Id" }, "doc_token": { "type": "string", "title": "Doc Token", "description": "Identificador do documento no provedor de assinatura." }, "lifecycle_status": { "type": "string", "title": "Lifecycle Status" }, "template_used": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Used" }, "is_first_contract": { "type": "boolean", "title": "Is First Contract", "description": "`true` na 1a cessao do cedente (template e autenticacao proprios)." }, "titles_count": { "type": "integer", "title": "Titles Count" }, "signers_count": { "type": "integer", "title": "Signers Count" }, "signers_notified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Signers Notified", "description": "`true` se a notificacao automatica foi enviada; `false` se falhou (re-tentada pelo recheck); `null` quando nao houve notificacao a enviar — em particular no modo `embedded`." }, "embedded": { "type": "boolean", "title": "Embedded", "description": "Modo embedded efetivamente aplicado neste despacho." }, "signers": { "items": { "$ref": "#/components/schemas/ContractDispatchSigner" }, "type": "array", "title": "Signers" } }, "type": "object", "required": [ "operation_id", "contract_id", "doc_token", "lifecycle_status", "is_first_contract", "titles_count", "signers_count", "embedded", "signers" ], "title": "ContractSendResponse", "description": "Resultado do despacho de contrato para assinatura." }, "ContractSignerStatus": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Nome do signatario." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Status do signatario no provedor." }, "signed": { "type": "boolean", "title": "Signed", "description": "`true` quando este signatario ja assinou." }, "sign_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sign Url", "description": "URL de assinatura do signatario — trate como CREDENCIAL: quem tem a URL assina. Pode vir `null` quando o provedor nao a expoe (ex.: documento ja finalizado)." } }, "type": "object", "required": [ "signed" ], "title": "ContractSignerStatus", "description": "Signatario como ele esta AGORA no provedor (leitura ao vivo)." }, "ContractSignersResponse": { "properties": { "operation_id": { "type": "string", "title": "Operation Id" }, "contract_id": { "type": "string", "title": "Contract Id" }, "doc_token": { "type": "string", "title": "Doc Token", "description": "Identificador do documento no provedor de assinatura." }, "document_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Status", "description": "Status do documento no provedor." }, "signers": { "items": { "$ref": "#/components/schemas/ContractSignerStatus" }, "type": "array", "title": "Signers" } }, "type": "object", "required": [ "operation_id", "contract_id", "doc_token", "signers" ], "title": "ContractSignersResponse", "description": "Signatarios do contrato de uma operacao, lidos AO VIVO no provedor." }, "DecimalRange": { "properties": { "min": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Min", "description": "Limite inferior (string decimal)" }, "max": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Max", "description": "Limite superior (string decimal)" } }, "type": "object", "title": "DecimalRange" }, "DirectOperationCreate": { "properties": { "name": { "type": "string", "maxLength": 150, "minLength": 2, "title": "Name", "description": "Nome ou razao social do cedente", "examples": [ "Empresa ABC Ltda" ] }, "type": { "type": "string", "title": "Type", "description": "Tipo de pessoa do cedente: `F` (fisica, exige `cpf`) ou `J` (juridica, exige `cnpj`). Comparacao SENSIVEL a caixa e sem validacao de dominio: qualquer valor diferente de `F`/`NATURAL_PERSON` e tratado como pessoa juridica.", "examples": [ "J" ] }, "cpf": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cpf", "description": "CPF do cedente (11 digitos). Obrigatorio se type='F'.", "examples": [ "12345678901" ] }, "cnpj": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cnpj", "description": "CNPJ do cedente (14 digitos). Obrigatorio se type='J'.", "examples": [ "12345678000195" ] }, "trade_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trade Name", "description": "Nome fantasia do cedente (opcional)" }, "email": { "type": "string", "title": "Email", "description": "Email do cedente para notificacoes e contrato", "examples": [ "cedente@empresa.com.br" ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone", "description": "Telefone do cedente (opcional)", "examples": [ "11999998888" ] }, "bank": { "$ref": "#/components/schemas/BankData", "description": "Dados de pagamento — obrigatorio. Enviar { use_document_pix: true } para PIX via CPF/CNPJ do cedente, ou { code, agency, account, type } para conta bancaria." }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "Endereco do cedente (opcional)" }, "fees": { "anyOf": [ { "$ref": "#/components/schemas/Fees" }, { "type": "null" } ], "description": "Taxas da operacao. Se omitido, usa hierarquia: cedente > sacado > policy do originador." }, "taxes": { "anyOf": [ { "$ref": "#/components/schemas/Fees" }, { "type": "null" } ], "description": "Alias para 'fees' (backward compatibility com V1)." }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id", "description": "ID do produto financeiro (opaco, definido pelo Backoffice). Filtra as policies de taxa por produto.", "examples": [ "b3f1c2a4-5d6e-7f80-9a1b-2c3d4e5f6a7b" ] }, "policy_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy Id", "description": "ID da policy do originador (override). Se informado, substitui a policy principal na resolucao.", "examples": [ "01970dc5-1234-7000-8000-000000000000" ] }, "signer_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Signer Ids", "description": "IDs dos representantes do cedente que ASSINAM o contrato (1 a 7, na ordem de assinatura). Obrigatorio (>=1) em operacoes criadas via Portal; opcional nos demais caminhos. Todos devem ser representantes ATIVOS do cedente da operacao — invalido => 422 fail-closed. Os dados sao SNAPSHOTADOS no create (edicao posterior do cadastro nao retroage no contrato)." }, "embedded_signature": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Embedded Signature", "description": "Assinatura EMBEDDED: com `true`, a notificacao automatica ao signatario NAO e enviada e o integrador apresenta ele mesmo a `sign_url` (obtida em `GET /v1/operations/{operation_id}/contract/signers`). Omitido ou `false` = comportamento padrao (o provedor notifica por e-mail). ATENCAO: em modo embedded nao ha lembrete nem watchdog — operacao cuja `sign_url` nunca for apresentada nunca sera assinada." }, "receivables": { "items": { "$ref": "#/components/schemas/Receivable" }, "type": "array", "minItems": 1, "title": "Receivables", "description": "Lista de recebiveis a antecipar." } }, "type": "object", "required": [ "name", "type", "email", "bank", "receivables" ], "title": "DirectOperationCreate" }, "DiscountCreditCreate": { "properties": { "assignor_id": { "type": "string", "title": "Assignor Id" }, "source_kind": { "type": "string", "maxLength": 40, "minLength": 2, "title": "Source Kind" }, "original_amount_brl": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" } ], "title": "Original Amount Brl" }, "reason": { "type": "string", "maxLength": 500, "minLength": 3, "title": "Reason" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 80, "minLength": 1 }, { "type": "null" } ], "title": "External Id", "description": "Identificador do credito no sistema do cliente. OPCIONAL. Quando enviado, o credito e deduplicado por (originador, external_id): um retry com o mesmo external_id devolve o credito ORIGINAL em vez de criar um segundo. Omitir mantem o comportamento atual." } }, "type": "object", "required": [ "assignor_id", "source_kind", "original_amount_brl", "reason" ], "title": "DiscountCreditCreate" }, "Fees": { "properties": { "monthly_rate_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Monthly Rate Pct", "description": "Taxa de juros mensal (%), aplicada pro-rata aos dias ate o vencimento. Cumulativa com discount_pct e fixed_discount_brl. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 3.5 ] }, "discount_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Discount Pct", "description": "Desagio fixo (%) sobre o valor, independente do prazo. Cumulativa com monthly_rate_pct e fixed_discount_brl. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 2.0 ] }, "fixed_discount_brl": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Fixed Discount Brl", "description": "Desconto nominal fixo em reais por recebivel. Cumulativo com monthly_rate_pct e discount_pct. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 150.0 ] }, "floating_days": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Floating Days", "description": "Dias de floating SOMADOS ao prazo cobrado no desagio pro-rata (monthly_rate_pct). Ex.: 25 dias + 2 floating => 27 dias cobrados. Default: usa valor da policy.", "examples": [ 2 ] }, "total_liquid_value_brl": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Total Liquid Value Brl", "description": "Valor liquido total desejado para TODA a operacao. O desconto e distribuido proporcionalmente ao face value de cada recebivel. MUTUAMENTE EXCLUSIVO com monthly_rate_pct, discount_pct e fixed_discount_brl. O CET resultante sera validado contra os limites da policy do originador.", "examples": [ 47500.0 ] } }, "type": "object", "title": "Fees", "description": "Taxas aplicadas a todos os recebiveis que NAO tiverem override individual.\n\nHierarquia de resolucao (por recebivel):\n 1. Taxa do recebivel (campos acima no Receivable)\n 2. Taxa da operacao (este objeto Fees)\n 3. Taxa padrao do cedente (assignor fee profile, gerenciado pelo Backoffice)\n 4. Taxa padrao do sacado (payer fee profile, gerenciado pelo Backoffice)\n 5. Taxa padrao do originador (originator policy, gerenciada pelo Backoffice)\n\nAs 3 modalidades de taxa sao CUMULATIVAS — podem ser combinadas." }, "FlowMode": { "properties": { "name": { "type": "string", "title": "Name", "description": "Nome do modo de operacao" }, "description": { "type": "string", "title": "Description", "description": "Descricao do modo" }, "steps": { "items": { "$ref": "#/components/schemas/FlowStep" }, "type": "array", "title": "Steps", "description": "Etapas do fluxo" } }, "type": "object", "required": [ "name", "description", "steps" ], "title": "FlowMode" }, "FlowResponse": { "properties": { "api_version": { "type": "string", "title": "Api Version", "description": "Versao da API", "examples": [ "1.0.0" ] }, "modes": { "items": { "$ref": "#/components/schemas/FlowMode" }, "type": "array", "title": "Modes", "description": "Modos de operacao disponiveis" }, "statuses": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Statuses", "description": "Status possiveis de operacao e suas descricoes" } }, "type": "object", "required": [ "api_version", "modes", "statuses" ], "title": "FlowResponse" }, "FlowStep": { "properties": { "step": { "type": "integer", "title": "Step", "description": "Numero da etapa" }, "name": { "type": "string", "title": "Name", "description": "Nome da etapa" }, "description": { "type": "string", "title": "Description", "description": "O que acontece nesta etapa" }, "endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Endpoint", "description": "Endpoint da API (null = automatico)" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Method", "description": "HTTP method" }, "required": { "type": "boolean", "title": "Required", "description": "Obrigatorio no fluxo" }, "next_steps": { "items": { "type": "integer" }, "type": "array", "title": "Next Steps", "description": "Proximas etapas possiveis" } }, "type": "object", "required": [ "step", "name", "description", "endpoint", "method", "required", "next_steps" ], "title": "FlowStep" }, "HTTPValidationError": { "properties": { "detail": { "anyOf": [ { "$ref": "#/components/schemas/ValidationErrorDetail" }, { "$ref": "#/components/schemas/StructuredErrorDetail" }, { "type": "string" } ], "title": "Detail", "description": "Falha de schema (objeto com `code: validation_error` e `errors`), erro de negocio estruturado (`code` + `message`) ou o codigo do erro como string." } }, "type": "object", "required": [ "detail" ], "title": "HTTPValidationError" }, "IntRange": { "properties": { "min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min" }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max" } }, "type": "object", "title": "IntRange" }, "LoginRequest": { "properties": { "email": { "type": "string", "maxLength": 254, "minLength": 5, "title": "Email" }, "password": { "type": "string", "maxLength": 256, "minLength": 8, "title": "Password" } }, "type": "object", "required": [ "email", "password" ], "title": "LoginRequest" }, "LoginResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "user": { "additionalProperties": true, "type": "object", "title": "User" } }, "type": "object", "required": [ "access_token", "user" ], "title": "LoginResponse" }, "OperationCreateResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "display_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Number" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/OperationLifecycleStatus" }, { "type": "null" } ], "title": "Status", "description": "ALIAS LEGADO do estado da operacao — na API publica e emitido APENAS por POST /v1/operations/direct, onde vale 'WAITING_APPROVAL' ou 'APPROVED_DIRECT' (auto-aprovada por caber no limite de auto-aprovacao da policy; sem limite configurado, sempre 'WAITING_APPROVAL'). Nulo/ausente em POST /v1/stock/request-anticipation. Nao e o campo autoritativo: use lifecycle_status (precedencia: lifecycle_status ?? status). Nao existe nas leituras (GET /v1/operations*) nem em nenhum payload de webhook.", "examples": [ "WAITING_APPROVAL" ] }, "lifecycle_status": { "anyOf": [ { "$ref": "#/components/schemas/OperationLifecycleStatus" }, { "type": "null" } ], "title": "Lifecycle Status", "description": "Estado AUTORITATIVO da operacao — espelha a coluna persistida (maquina de estado do Lifecycle) e e o unico campo de estado presente em GET /v1/operations e GET /v1/operations/{id}. Preenchido por POST /v1/stock/request-anticipation ('WAITING_APPROVAL' ou 'APPROVED_DIRECT' quando dentro do limite de auto-aprovacao); nulo/ausente em POST /v1/operations/direct, que emite o alias legado `status`. Nunca vem preenchido junto com `status`. ATENCAO nos webhooks: apenas os eventos operation.created e operation.approved carregam este campo no payload; nos demais eventos operation.* ele NAO vem (busque o estado com GET /v1/operations/{id}).", "examples": [ "WAITING_APPROVAL" ] }, "opr_gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Future Value", "description": "Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Nome CANONICO publico; equivale EXATAMENTE a `opr_gross_face_value` (mesmo numero, mesma semantica)." }, "opr_net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Future Value", "description": "Net Face Value (NFV) agregado da operacao — a soma do `net_face_value` dos recebiveis, ou seja o valor de face FUTURO LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros). MESMA agregacao nas 4 portas (`/v1/operations/direct`, `/v1/simulate`, `/v1/stock/request-anticipation`, `/v1/stock/simulate-anticipation`). Numa antecipacao PARCIAL pelo fluxo direto este campo reporta o NFV INTEIRO, nao o valor antecipado — a base do desagio dessa operacao e a soma de `requested_advance_value` item a item, disponivel em `receivables[]`. No fluxo de ESTOQUE este campo E a base do desagio (100% dos itens). Nome CANONICO publico; equivale EXATAMENTE a `opr_net_face_value` (mesmo numero, mesma semantica)." }, "opr_present_value_discount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Present Value Discount", "description": "Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Nome CANONICO publico; equivale EXATAMENTE a `opr_discounted_value` (mesmo numero, mesma semantica)." }, "opr_net_present_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Present Liquid Value", "description": "Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Nome CANONICO publico; equivale EXATAMENTE a `opr_liquid_value` (mesmo numero, mesma semantica)." }, "opr_net_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Liquid Value", "description": "Projecao INFORMATIVA de `opr_liquid_value` menos `other_debt_discounts`. Nao e persistida e NAO e o valor pago: o PIX ao cedente usa `opr_liquid_value`. Nao concilie o pagamento por este campo. O `net` daqui nao tem relacao com o `net` do Net Face Value (`net_face_value`): la significa face liquido de descontos do lastro, aqui significa liquido projetado de debitos vencidos do cedente." }, "other_debt_discounts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Other Debt Discounts", "description": "Saldo devedor total dos titulos VENCIDOS e ainda em aberto do mesmo cedente junto a este originador, apurado no momento da criacao. Valor informativo — nao e abatido do pagamento desta operacao." }, "average_days_in_advance": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Average Days In Advance", "description": "Prazo medio simples da operacao, em dias: media aritmetica TRUNCADA dos dias ate o vencimento dos recebiveis. Nao e ponderada por valor e NAO inclui `floating_days`." }, "floating_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Floating Days", "description": "Dias de floating aplicados, SOMADOS ao prazo ate o vencimento para formar os dias cobrados no desagio (ex.: 25 dias de prazo + 2 de floating = 27 dias cobrados). O float e custo do funder, nao carencia do cedente." }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id" }, "disbursement_method": { "anyOf": [ { "$ref": "#/components/schemas/DisbursementMethod" }, { "type": "null" } ], "title": "Disbursement Method", "description": "Como o cedente sera DESEMBOLSADO nesta operacao — reflete a conta primaria que ficou valendo, nao o `bank` enviado. `pix_document`: PIX na chave do CPF/CNPJ do cedente; inclui o FALLBACK SILENCIOSO — dado bancario AUSENTE ou vazio (`code`, `agency` ou `account`) nao retorna erro, cai aqui. A checagem e de preenchimento, nao de validade: dado bancario ERRADO porem presente NAO cai no fallback, segue como `bank_account`. `bank_account`: transferencia para a conta informada (so quando os TRES vieram preenchidos). Se o cedente ja tinha conta primaria, o `bank` desta chamada foi IGNORADO e o valor descreve a conta PREEXISTENTE. Campo ADITIVO e opcional: nulo quando o metodo nao pode ser determinado. Este schema de resposta e COMPARTILHADO pelas duas portas de criacao; nesta versao so POST /v1/operations/direct preenche o campo — em POST /v1/stock/request-anticipation ele vem sempre `null`.", "examples": [ "pix_document" ] }, "needs_backoffice_approval": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Needs Backoffice Approval", "description": "Veredito de ALCADA desta operacao. `true`: ela entrou na fila de aprovacao do Backoffice (nasceu `WAITING_APPROVAL`). `false`: o total SOLICITADO coube no limite de auto-aprovacao da policy e a operacao ja nasceu aprovada (`APPROVED_DIRECT`). Limite NAO configurado (ausente ou zero) da `true` — fail-closed, nunca aprovacao automatica. O campo ESPELHA o estado que a propria resposta ja traz (`lifecycle_status ?? status`): as duas portas de criacao usam o MESMO gate, entao ler um ou outro da a mesma conclusao. Campo ADITIVO em POST /v1/operations/direct, que antes o devolvia sempre `null`.", "examples": [ true ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "titles": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Titles", "description": "Titulos criados. Cada item traz os valores nos DOIS vocabularios: `requested_advance_value`/`requested_net_future_value`, `discounted_value`/`present_value_discount` e `liquid_value`/`net_present_liquid_value` (espelho aplicado no emissor via `mirror_dict`). O objeto nao e tipado no schema — os campos nao aparecem em `components.schemas`." }, "opr_gross_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Face Value", "description": "[DEPRECATED — use `opr_gross_future_value`] Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Face Value", "description": "[DEPRECATED — use `opr_net_future_value`] Net Face Value (NFV) agregado da operacao — a soma do `net_face_value` dos recebiveis, ou seja o valor de face FUTURO LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros). MESMA agregacao nas 4 portas (`/v1/operations/direct`, `/v1/simulate`, `/v1/stock/request-anticipation`, `/v1/stock/simulate-anticipation`). Numa antecipacao PARCIAL pelo fluxo direto este campo reporta o NFV INTEIRO, nao o valor antecipado — a base do desagio dessa operacao e a soma de `requested_advance_value` item a item, disponivel em `receivables[]`. No fluxo de ESTOQUE este campo E a base do desagio (100% dos itens). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_discounted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Discounted Value", "description": "[DEPRECATED — use `opr_present_value_discount`] Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Liquid Value", "description": "[DEPRECATED — use `opr_net_present_liquid_value`] Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "additionalProperties": true, "type": "object", "required": [ "id" ], "title": "OperationCreateResponse", "description": "Resposta dos endpoints de criacao de operacao.\n\nCobre `POST /v1/operations/direct` e `POST /v1/stock/request-anticipation`.\n`extra=\"allow\"` preserva campos adicionais (ex.: contract_details, fee_hierarchy)." }, "OperationDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "display_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Number", "description": "Numero de exibicao da operacao (ex.: `OP-A1B2C3D4-E5F6G7H8`)." }, "assignor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" }, "opr_gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Future Value", "description": "Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Nome CANONICO publico; equivale EXATAMENTE a `opr_gross_face_value` (mesmo numero, mesma semantica)." }, "opr_present_value_discount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Present Value Discount", "description": "Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Nome CANONICO publico; equivale EXATAMENTE a `opr_discounted_value` (mesmo numero, mesma semantica)." }, "opr_net_present_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Present Liquid Value", "description": "Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Nome CANONICO publico; equivale EXATAMENTE a `opr_liquid_value` (mesmo numero, mesma semantica)." }, "total_tac": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Tac", "description": "`total_fixed_tac` + `total_variable_tac`. Hoje sempre `0.00`: as portas de criacao da API V2 nao cobram TAC." }, "total_effective_cost_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Effective Cost Pct", "description": "Custo efetivo total da operacao em %, com 4 casas: `opr_discounted_value` dividido pela BASE do desagio (nao por `opr_gross_face_value`) x 100. E o custo do PERIODO da operacao — nao e taxa mensal nem anualizada." }, "lifecycle_status": { "title": "Lifecycle Status", "$ref": "#/components/schemas/OperationLifecycleStatus" }, "returning_status": { "anyOf": [ { "$ref": "#/components/schemas/OperationReturningStatus" }, { "type": "null" } ], "title": "Returning Status" }, "contract_signed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Contract Signed At" }, "payment_sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Payment Sent At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "originator_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Originator Id" }, "applied_fees_snapshot": { "anyOf": [ {}, { "type": "null" } ], "title": "Applied Fees Snapshot" }, "total_fixed_tac": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Fixed Tac", "description": "Parcela FIXA (em R$) da TAC cobrada na operacao. Hoje sempre `0.00`: as portas de criacao da API V2 nao cobram TAC." }, "total_variable_tac": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Variable Tac", "description": "Parcela VARIAVEL (percentual sobre o valor da operacao) da TAC. Hoje sempre `0.00`: as portas de criacao da API V2 nao cobram TAC." }, "pix_transfer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pix Transfer Id" }, "payment_completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Payment Completed At" }, "approved_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Approved At" }, "cancelled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Cancelled At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "opr_gross_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Face Value", "description": "[DEPRECATED — use `opr_gross_future_value`] Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Liquid Value", "description": "[DEPRECATED — use `opr_net_present_liquid_value`] Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_discounted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Discounted Value", "description": "[DEPRECATED — use `opr_present_value_discount`] Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "id", "lifecycle_status", "created_at" ], "title": "OperationDetail" }, "OperationListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/OperationSummary" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "items", "total" ], "title": "OperationListResponse" }, "OperationSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "display_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Number", "description": "Numero de exibicao da operacao (ex.: `OP-A1B2C3D4-E5F6G7H8`)." }, "assignor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" }, "opr_gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Future Value", "description": "Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Nome CANONICO publico; equivale EXATAMENTE a `opr_gross_face_value` (mesmo numero, mesma semantica)." }, "opr_present_value_discount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Present Value Discount", "description": "Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Nome CANONICO publico; equivale EXATAMENTE a `opr_discounted_value` (mesmo numero, mesma semantica)." }, "opr_net_present_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Present Liquid Value", "description": "Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Nome CANONICO publico; equivale EXATAMENTE a `opr_liquid_value` (mesmo numero, mesma semantica)." }, "total_tac": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Tac", "description": "TAC total da operacao (Taxa de Abertura de Credito) = `total_fixed_tac` + `total_variable_tac`. Categoria de tarifa distinta de juros/desagio e de mora. Hoje sempre `0.00`: as portas de criacao da API V2 nao cobram TAC." }, "total_effective_cost_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Effective Cost Pct", "description": "Custo efetivo total da operacao em %, com 4 casas: `opr_discounted_value` dividido pela BASE do desagio (nao por `opr_gross_face_value`) x 100. E o custo do PERIODO da operacao — nao e taxa mensal nem anualizada." }, "lifecycle_status": { "title": "Lifecycle Status", "$ref": "#/components/schemas/OperationLifecycleStatus" }, "returning_status": { "anyOf": [ { "$ref": "#/components/schemas/OperationReturningStatus" }, { "type": "null" } ], "title": "Returning Status" }, "contract_signed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Contract Signed At" }, "payment_sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Payment Sent At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "opr_gross_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Face Value", "description": "[DEPRECATED — use `opr_gross_future_value`] Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Liquid Value", "description": "[DEPRECATED — use `opr_net_present_liquid_value`] Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_discounted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Discounted Value", "description": "[DEPRECATED — use `opr_present_value_discount`] Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "id", "lifecycle_status", "created_at" ], "title": "OperationSummary" }, "OriginatorMe": { "properties": { "id": { "type": "string", "title": "Id" }, "cnpj": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cnpj" }, "legal_name": { "type": "string", "title": "Legal Name" }, "trade_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trade Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "kind": { "anyOf": [ { "$ref": "#/components/schemas/OriginatorKind" }, { "type": "null" } ], "title": "Kind" }, "primary_backing_type": { "anyOf": [ { "$ref": "#/components/schemas/ReceivableBackingType" }, { "type": "null" } ], "title": "Primary Backing Type" }, "liquidation_method": { "anyOf": [ { "$ref": "#/components/schemas/LiquidationMethod" }, { "type": "null" } ], "title": "Liquidation Method" }, "brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand Name" }, "active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Active" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "legal_name" ], "title": "OriginatorMe" }, "PayableCreate": { "properties": { "assignor_id": { "type": "string", "title": "Assignor Id" }, "counterparty_kind": { "type": "string", "title": "Counterparty Kind", "default": "ORIGINATOR_DIRECT" }, "counterparty_payer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Counterparty Payer Id" }, "kind": { "type": "string", "title": "Kind" }, "originating_title_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Originating Title Id" }, "originating_operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Originating Operation Id" }, "amount_brl": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" } ], "title": "Amount Brl" }, "reason": { "type": "string", "maxLength": 500, "minLength": 3, "title": "Reason" }, "due_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Due Date" } }, "type": "object", "required": [ "assignor_id", "kind", "amount_brl", "reason" ], "title": "PayableCreate" }, "PayablePaymentRecord": { "properties": { "source": { "type": "string", "title": "Source" }, "paid_amount_brl": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" } ], "title": "Paid Amount Brl" }, "capital_inflow_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Capital Inflow Id" }, "offsetting_operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Offsetting Operation Id" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 80, "minLength": 1 }, { "type": "null" } ], "title": "External Id", "description": "Identificador do pagamento no sistema do cliente. OPCIONAL. Quando enviado, o registro e deduplicado por (payable, external_id): um retry com o mesmo external_id devolve o pagamento ORIGINAL em vez de registrar um segundo debito. Omitir mantem o comportamento atual." } }, "type": "object", "required": [ "source", "paid_amount_brl" ], "title": "PayablePaymentRecord" }, "PayerCreate": { "properties": { "cnpj": { "type": "string", "maxLength": 18, "minLength": 11, "title": "Cnpj", "description": "Documento do sacado: CPF (11 digitos) ou CNPJ (14 digitos). Aceita pontuacao (ex: 12.345.678/0001-95 ou 123.456.789-09) — e normalizado para apenas digitos. O digito verificador e validado; documento invalido retorna 422. Dedup por (originador, documento).", "examples": [ "12345678000195", "12345678909" ] }, "legal_name": { "type": "string", "maxLength": 150, "minLength": 2, "title": "Legal Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "zip_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Zip Code" }, "street": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Street" }, "street_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Street Number" }, "complement": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Complement" }, "neighborhood": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Neighborhood" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" } }, "type": "object", "required": [ "cnpj", "legal_name" ], "title": "PayerCreate" }, "PayerCreateResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "cnpj": { "type": "string", "title": "Cnpj" }, "legal_name": { "type": "string", "title": "Legal Name" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "cnpj", "legal_name", "created_at" ], "title": "PayerCreateResponse" }, "PayerDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "cnpj": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cnpj" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "approve_automatic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Approve Automatic" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "originator_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Originator Id" }, "zip_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Zip Code" }, "street": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Street" }, "street_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Street Number" }, "complement": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Complement" }, "neighborhood": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Neighborhood" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "override_default_tax_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Override Default Tax Pct" }, "override_fixed_tac_brl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Override Fixed Tac Brl" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "legal_name" ], "title": "PayerDetail" }, "PayerListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PayerSummary" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "items", "total" ], "title": "PayerListResponse" }, "PayerSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "cnpj": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cnpj" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "approve_automatic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Approve Automatic" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "legal_name" ], "title": "PayerSummary" }, "PayerUpdate": { "properties": { "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "zip_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Zip Code" }, "street": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Street" }, "street_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Street Number" }, "complement": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Complement" }, "neighborhood": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Neighborhood" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "approve_automatic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Approve Automatic" } }, "type": "object", "title": "PayerUpdate" }, "PayerUpdateResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Name" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id" ], "title": "PayerUpdateResponse" }, "PolicyUsedResponse": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "ID da policy usada" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Nome da policy" }, "source": { "title": "Source", "description": "Entidade de onde veio a POLICY resolvida (`assignor`, `payer` ou `policy`), ou `default` quando nenhuma policy foi resolvida. Taxa vinda do payload NAO aparece aqui: neste caso o campo fica em `default` e a origem real esta em `receivables[].fee_source`.", "$ref": "#/components/schemas/FeePolicySource" }, "monthly_rate_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Monthly Rate Pct", "description": "Taxa mensal aplicada" }, "rate_from_schedule": { "type": "boolean", "title": "Rate From Schedule", "description": "Se a taxa veio do rate_schedule (escalonada por PMP)", "default": false }, "schedule_day_used": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Schedule Day Used", "description": "Dia do PMP usado no rate_schedule" } }, "type": "object", "required": [ "source" ], "title": "PolicyUsedResponse" }, "Product": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "ID do produto a usar em product_id nas rotas de operacao/simulacao" }, "product_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Type", "description": "Tipo/risco do produto (metadata do BO)" }, "policy_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy Slug", "description": "ID logico estavel da policy (entre versoes)" }, "policy_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy Name" }, "policy_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Policy Version" }, "is_primary": { "type": "boolean", "title": "Is Primary", "description": "Produto/policy padrao do originador", "default": false }, "monthly_rate_pct": { "$ref": "#/components/schemas/DecimalRange", "description": "Faixa permitida de juros mensal (a.m.)" }, "term_days": { "$ref": "#/components/schemas/IntRange", "description": "Faixa permitida de prazo (dias)" }, "operation_value_brl": { "$ref": "#/components/schemas/DecimalRange", "description": "Faixa permitida de valor da operacao (BRL)" }, "assigned_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned At", "description": "Quando a policy foi atribuida (ISO-8601)" } }, "type": "object", "required": [ "product_id", "monthly_rate_pct", "term_days", "operation_value_brl" ], "title": "Product" }, "ProductsResponse": { "properties": { "products": { "items": { "$ref": "#/components/schemas/Product" }, "type": "array", "title": "Products" }, "total": { "type": "integer", "title": "Total", "description": "Total de produtos que casam com os filtros (antes da paginacao)" }, "limit": { "type": "integer", "title": "Limit", "description": "Tamanho da pagina aplicado" }, "offset": { "type": "integer", "title": "Offset", "description": "Deslocamento aplicado" } }, "type": "object", "required": [ "products", "total", "limit", "offset" ], "title": "ProductsResponse" }, "Receivable": { "properties": { "external_id": { "type": "string", "title": "External Id", "description": "Identificador unico do recebivel no sistema do originador (ex: numero da NF). Deve ser unico por operacao. QUANDO USAR: e a sua chave de conciliacao — e por ela que voce reencontra o recebivel no estoque, nos titulos e nos webhooks. Use o identificador que o SEU sistema ja conhece (numero da NF, id do ERP), nao um UUID novo.", "examples": [ "NF-2026-001" ] }, "identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Identifier", "description": "Identificador interno opcional para referencia cruzada (ex: ID no ERP do cedente). QUANDO USAR: um segundo rotulo, livre, para quando o `external_id` ja esta ocupado pelo numero da NF e voce precisa carregar tambem a chave do seu ERP. Ex.: `external_id` = 'NF-2026-001' e `identifier` = 'REC-88213'. Nao participa de nenhuma regra de unicidade.", "examples": [ "REC-001" ] }, "payer_name": { "type": "string", "title": "Payer Name", "description": "Nome ou razao social do sacado (devedor do recebivel). QUANDO USAR: e o nome que sai no CONTRATO de cessao assinado pelo Cedente. Use a razao social como esta na NF-e, nao o nome fantasia.", "examples": [ "Empresa XYZ Ltda" ] }, "payer_document": { "type": "string", "title": "Payer Document", "description": "CPF (11 digitos) ou CNPJ (14 digitos) do sacado. QUANDO USAR: e a identidade do sacado para a API. Sacado novo e cadastrado na hora; sacado que ja existe e reaproveitado pelo documento (dedup), entao o mesmo CNPJ em duas operacoes e o MESMO sacado — e por ele que os limites de exposicao por sacado se acumulam. Envie so digitos ou com pontuacao, tanto faz; digito verificador invalido e recusado.", "examples": [ "98765432000198" ] }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "title": "Due Date", "description": "Data de vencimento do recebivel (YYYY-MM-DD). Quanto mais distante, maior o desconto por antecipacao. QUANDO USAR: e o vencimento acordado com o sacado, e o que define o PRAZO cobrado. Ex.: 60 dias a 3,5% a.m. custam o dobro de 30 dias. Vencimento errado nao e recusado — ele so muda o preco, entao confira.", "examples": [ "2026-08-15" ] }, "backing_type": { "anyOf": [ { "$ref": "#/components/schemas/ReceivableBackingType" }, { "type": "null" } ], "title": "Backing Type", "description": "Tipo de lastro do recebivel (enum receivable_backing_type do banco). Opcional — ausente/null assume NFE (comportamento historico preservado). Valor fora do enum => 422 com a lista dos 25 valores validos (ex: NFE, NFSE, CTE, TRADE_BILL, BOLETO, RECURRING_CONTRACT...). QUANDO USAR: quando o lastro NAO e nota fiscal de produto. Ex.: um contrato de servico recorrente vai como `RECURRING_CONTRACT` e um boleto como `BOLETO`. O tipo escolhido aparece no contrato de cessao, e o item-resto de uma antecipacao parcial o herda.", "examples": [ "NFE" ] }, "gross_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do lastro/recebivel (ex: valor total da NF-e, antes dos descontos aplicados ao lastro). Opcional — se omitido, assume o mesmo valor do Net Future Value. Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica). ATENCAO — nao e substituicao 1:1 do nome deprecado: usar este campo EXIGE `gross_future_value_deductions` no mesmo payload (envie `0` se nao houver deducoes), senao 422 `DEDUCTIONS_REQUIRED_WITH_GROSS`. O nome deprecado segue aceito sozinho. QUANDO USAR: informe o bruto quando o valor da NF-e e MAIOR que o que sobra para antecipar — tipicamente por imposto retido na fonte ou glosa do sacado. Serve de conferencia (a API recusa NFV acima do bruto) e alimenta os limites agregados de exposicao. Se bruto e NFV coincidem, pode omitir os dois campos de bruto. OBRIGATORIEDADE: este campo e OPCIONAL nesta rota; omitido, a API assume bruto = `net_future_value`. Ja o `net_future_value` e SEMPRE obrigatorio — nao existe a forma 'mando o bruto e as deducoes e voce calcula o NFV'.", "examples": [ 12000.0 ] }, "gross_future_value_deductions": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Gross Future Value Deductions", "description": "Descontos ja aplicados ao lastro, DECLARADOS: `gross_future_value - net_future_value`. Informacao gerencial — NAO entra no calculo do desagio. Obrigatorio quando `gross_future_value` e informado (envie `0` para declarar 'sem deducoes'); vindo os tres valores, a decomposicao tem que fechar EXATAMENTE, senao 422 `VALUE_DECOMPOSITION_MISMATCH`. QUANDO USAR: e o campo que EXPLICA a diferenca entre o bruto e o NFV, para ela nunca ficar implicita. Ex.: NF-e de R$12.000 com R$1.500 de ISS e IRRF retidos na fonte e R$500 de glosa do sacado => `gross_future_value` = 12000, `gross_future_value_deductions` = 2000, `net_future_value` = 10000. Nao ha desconto no lastro? Mande `0` — declarar 'sem deducoes' e diferente de nao declarar. Este numero e GERENCIAL: nao entra em nenhuma conta de desagio nem de pagamento. OBRIGATORIEDADE: exigido SO quando `gross_future_value` e informado; enviado sem o bruto, e ignorado, e ele nao substitui o `net_future_value`.", "examples": [ 2000.0 ] }, "net_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Net Future Value", "description": "Net Future Value do recebivel — valor de face FUTURO, LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros; ex: valor da NF-e apos deducoes). E o teto da antecipacao: o valor solicitado nao pode exceder este valor. Nome CANONICO publico; equivale EXATAMENTE a `net_face_value` (mesmo numero, mesma semantica). QUANDO USAR: e o campo que responde 'quanto deste recebivel existe para antecipar'. Ex.: NF-e de R$12.000 com R$2.000 de imposto retido na fonte => `net_future_value` = 10000. E dele que sai o teto do pedido e, no fluxo de estoque, a base do desagio. OBRIGATORIEDADE: SEMPRE obrigatorio (sob este nome ou sob `net_face_value`). A API nunca deriva o NFV de `gross_future_value` menos `gross_future_value_deductions` — mandar so esses dois nao substitui este campo.", "examples": [ 10000.0 ] }, "requested_net_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Requested Net Future Value", "description": "Quanto do Net Future Value esta sendo antecipado deste recebivel (BRL, valor ABSOLUTO; o equivalente percentual e `requested_net_future_value_percent`). Deve ser <= `net_future_value`. Se igual, antecipacao de 100%. Se menor, antecipacao PARCIAL: o restante do NFV volta ao ESTOQUE como item novo IN_STOCK, com external_id `_REMAINDER_<8 primeiros caracteres do id da operacao>` — sufixo proprio para nao conflitar com a NF de origem, que permanece unica por (originador, external_id). O item-resto herda backing_type e os dados de NF-e da origem, e recebe o `gross_future_value` RATEADO na proporcao da nota (`gross_origem x NFV_resto / NFV_origem`, arredondado para baixo ao centavo), para que a diferenca gerencial entre bruto e NFV sobreviva na parte que voltou ao estoque. ATENCAO ao `pre_authorized`: o item-resto nasce SEMPRE `false` (bloqueado), qualquer que seja o estado do item de origem no estoque — antecipar o resto sem liberar antes e recusado com 409 `stock_item__not_pre_authorized`. Libere com `PATCH /v1/stock/{item_id}` (`pre_authorized: true`). Nome CANONICO publico; equivale EXATAMENTE a `requested_advance_value` (mesmo numero, mesma semantica). QUANDO USAR: e o campo do quanto o Cedente quer receber deste recebivel, em BRL. Ex.: recebivel com NFV de R$10.000 e o Cedente so precisa de R$6.000 agora => `requested_net_future_value` = 6000, e os R$4.000 restantes voltam ao estoque para uma antecipacao futura. Igual ao NFV = antecipacao de 100%.", "examples": [ 10000.0 ] }, "requested_net_future_value_percent": { "anyOf": [ { "type": "number", "maximum": 100.0, "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,3}|(?=[\\d.]{1,6}0*$)\\d{0,3}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Requested Net Future Value Percent", "description": "Percentual do Net Future Value a antecipar (0 < valor <= 100). Alternativa ao valor ABSOLUTO — MUTUAMENTE EXCLUSIVO com `requested_net_future_value` e `requested_advance_value` (os dois juntos => 422 `REQUESTED_VALUE_AMBIGUOUS`). Resolucao: `percent / 100 * net_future_value`, arredondado a centavos SEMPRE PARA BAIXO; `100` devolve o NFV EXATO (sem arredondamento). Nao existe nas portas de `/v1/stock/*`, que antecipam sempre 100% dos itens. QUANDO USAR: quando a sua regra de negocio e percentual e nao em reais — 'este Cedente antecipa 60% de cada nota'. Ex.: NFV de R$10.000 com `requested_net_future_value_percent` = 60 antecipa R$6.000, sem voce fazer a conta. Para 100% do NFV o percentual e mais seguro que o valor absoluto: `100` devolve o NFV EXATO, sem risco de errar o ultimo centavo.", "examples": [ 60.0 ] }, "monthly_rate_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Monthly Rate Pct", "description": "Taxa de juros mensal (%), aplicada pro-rata aos dias ate o vencimento (juros simples, base 30). Ex: 3.5 = 3.5% a.m. Um recebivel de R$10.000 com vencimento em 60 dias: desconto = 10000 * 3.5/100 * 60/30 = R$700,00. Pode ser combinada com discount_pct e fixed_discount_brl (cumulativo). QUANDO USAR: quando VOCE define o preco desta operacao em vez de deixar a policy do originador decidir. E a forma mais comum de override, porque o custo acompanha o prazo: o mesmo recebivel custa mais se vencer mais longe. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 3.5 ] }, "discount_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Discount Pct", "description": "Desagio fixo (%) sobre o valor antecipado, independente do prazo. Ex: 2.0 = 2% de desconto. R$10.000 * 2% = R$200 de desconto. Util quando a taxa nao depende do tempo ate o vencimento. QUANDO USAR: para um custo que NAO depende do prazo — uma taxa de estruturacao ou um spread fixo por operacao. Ex.: 3.5 de `monthly_rate_pct` mais 2.0 de `discount_pct` cobra os dois, somados. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 2.0 ] }, "fixed_discount_brl": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Fixed Discount Brl", "description": "Desconto nominal fixo em reais, aplicado diretamente. Ex: 500.00 = R$500 de desconto, independente do valor ou prazo do recebivel. QUANDO USAR: para uma tarifa em reais, do tipo TAC. Cuidado com recebivel pequeno: como o valor NAO escala, uma tarifa de R$500 sobre um recebivel de R$400 zeraria o liquido e a API recusa com 422 `RECEIVABLE_DISCOUNT_EXCEEDS_BASE`. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 500.0 ] }, "liquid_value_brl": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Liquid Value Brl", "description": "Valor liquido que o cedente deve receber por este recebivel. O sistema calcula o desconto reverso: desconto = value - liquid_value_brl. MUTUAMENTE EXCLUSIVO com monthly_rate_pct, discount_pct e fixed_discount_brl. QUANDO USAR: se voce quiser mandar direto o valor liquido que o Cedente deve receber por esse recebivel, sem se preocupar com taxa de juros, esse e o campo. Ex.: recebivel de R$1.000 que voce acordou vender por R$600 — nao precisa calcular taxa nem prazo, mande `liquid_value_brl` = 600, o valor efetivo que vamos desembolsar. A API faz o caminho inverso (desagio = base menos o liquido) e valida o CET resultante contra os limites da policy do originador — CET fora da faixa e 422 `CET_OUT_OF_BOUNDS`.", "examples": [ 9500.0 ] }, "gross_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do lastro/recebivel (ex: valor total da NF-e, antes dos descontos aplicados ao lastro). Opcional — se omitido, assume o mesmo valor do Net Future Value. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico.", "examples": [ 12000.0 ] }, "net_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" } ], "title": "Net Face Value", "description": "[DEPRECATED — use `net_future_value`] Net Future Value do recebivel — valor de face FUTURO, LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros; ex: valor da NF-e apos deducoes). E o teto da antecipacao: o valor solicitado nao pode exceder este valor. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico.", "examples": [ 10000.0 ] }, "requested_advance_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" } ], "title": "Requested Advance Value", "description": "[DEPRECATED — use `requested_net_future_value`] Quanto do Net Future Value esta sendo antecipado deste recebivel (BRL, valor ABSOLUTO; o equivalente percentual e `requested_net_future_value_percent`). Deve ser <= `net_future_value`. Se igual, antecipacao de 100%. Se menor, antecipacao PARCIAL: o restante do NFV volta ao ESTOQUE como item novo IN_STOCK, com external_id `_REMAINDER_<8 primeiros caracteres do id da operacao>` — sufixo proprio para nao conflitar com a NF de origem, que permanece unica por (originador, external_id). O item-resto herda backing_type e os dados de NF-e da origem, e recebe o `gross_future_value` RATEADO na proporcao da nota (`gross_origem x NFV_resto / NFV_origem`, arredondado para baixo ao centavo), para que a diferenca gerencial entre bruto e NFV sobreviva na parte que voltou ao estoque. ATENCAO ao `pre_authorized`: o item-resto nasce SEMPRE `false` (bloqueado), qualquer que seja o estado do item de origem no estoque — antecipar o resto sem liberar antes e recusado com 409 `stock_item__not_pre_authorized`. Libere com `PATCH /v1/stock/{item_id}` (`pre_authorized: true`). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico.", "examples": [ 10000.0 ] } }, "type": "object", "required": [ "external_id", "payer_name", "payer_document", "net_face_value", "requested_advance_value", "due_date" ], "title": "Receivable" }, "RequestAnticipationFromStock": { "properties": { "stock_item_ids": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Stock Item Ids", "description": "IDs dos itens de estoque a antecipar" }, "requested_net_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Requested Net Future Value", "description": "Obrigatorio e VALIDADO: deve ser EXATAMENTE igual a soma do Net Future Value (`net_future_value`) dos itens em `stock_item_ids`. Qualquer outro valor => `422` com `detail.code` `STOCK_REQUESTED_VALUE_MISMATCH`. O fluxo de estoque antecipa sempre 100% dos itens selecionados, com desagio sobre o NFV de cada um; antecipacao PARCIAL (percentual do NFV, com o restante voltando ao estoque) so existe em `POST /v1/operations/direct` — e por isso `requested_net_future_value_percent` NAO existe nesta porta. Para fixar o liquido a receber use `fees.total_liquid_value_brl`. Nome CANONICO publico; equivale EXATAMENTE a `requested_advance_value` (mesmo numero, mesma semantica)." }, "bank": { "$ref": "#/components/schemas/StockBankData", "description": "Dados de pagamento — obrigatorio" }, "fees": { "anyOf": [ { "$ref": "#/components/schemas/StockAnticipationFees" }, { "type": "null" } ], "description": "Taxas da operacao. Se omitido, usa hierarquia de taxas." }, "taxes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Taxes", "description": "Alias para 'fees' (backward compat)" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id", "description": "ID do produto financeiro (opaco, definido pelo Backoffice). Filtra a policy de taxa por produto.", "examples": [ "b3f1c2a4-5d6e-7f80-9a1b-2c3d4e5f6a7b" ] }, "policy_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy Id", "description": "ID da policy do originador (override). Se informado, substitui a policy principal na resolucao.", "examples": [ "01970dc5-1234-7000-8000-000000000000" ] }, "embedded_signature": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Embedded Signature", "description": "Assinatura EMBEDDED: com `true`, a notificacao automatica ao signatario NAO e enviada e o integrador apresenta ele mesmo a `sign_url` (obtida em `GET /v1/operations/{operation_id}/contract/signers`). Omitido ou `false` = comportamento padrao (o provedor notifica por e-mail). ATENCAO: em modo embedded nao ha lembrete nem watchdog — operacao cuja `sign_url` nunca for apresentada nunca sera assinada." }, "requested_advance_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" } ], "title": "Requested Advance Value", "description": "[DEPRECATED — use `requested_net_future_value`] Obrigatorio e VALIDADO: deve ser EXATAMENTE igual a soma do Net Future Value (`net_future_value`) dos itens em `stock_item_ids`. Qualquer outro valor => `422` com `detail.code` `STOCK_REQUESTED_VALUE_MISMATCH`. O fluxo de estoque antecipa sempre 100% dos itens selecionados, com desagio sobre o NFV de cada um; antecipacao PARCIAL (percentual do NFV, com o restante voltando ao estoque) so existe em `POST /v1/operations/direct` — e por isso `requested_net_future_value_percent` NAO existe nesta porta. Para fixar o liquido a receber use `fees.total_liquid_value_brl`. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "stock_item_ids", "requested_advance_value", "bank" ], "title": "RequestAnticipationFromStock" }, "SendContractForOperationEmbeddedRequest": { "properties": { "embedded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Embedded", "description": "Modo EMBEDDED: `true` silencia a notificacao automatica aos signatarios (nenhum e-mail sai da ZapSign) — o integrador assume a responsabilidade de apresentar as `sign_url` devolvidas. `false` forca a notificacao automatica. Omitido (`null`) = o default da operacao. ATENCAO: em modo embedded nao ha watchdog nem lembrete — operacao cujo `sign_url` nunca for apresentado nunca sera assinada." } }, "type": "object", "title": "SendContractForOperationEmbeddedRequest", "description": "Corpo (OPCIONAL) do disparo publico de contrato." }, "SimulateAnticipationFromStock": { "properties": { "stock_item_ids": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Stock Item Ids", "description": "IDs dos itens de estoque a simular" }, "requested_net_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Requested Net Future Value", "description": "Obrigatorio e VALIDADO com o MESMO criterio do `request-anticipation` (veredito simulado = veredito do request): deve ser EXATAMENTE igual a soma do Net Future Value (`net_future_value`) dos itens em `stock_item_ids`; qualquer outro valor => `422` com `detail.code` `STOCK_REQUESTED_VALUE_MISMATCH`. A simulacao considera sempre 100% dos itens, com desagio sobre o NFV de cada um. Para fixar o liquido alvo use `fees.total_liquid_value_brl`. Nome CANONICO publico; equivale EXATAMENTE a `requested_advance_value` (mesmo numero, mesma semantica)." }, "fees": { "anyOf": [ { "$ref": "#/components/schemas/StockAnticipationFees" }, { "type": "null" } ], "description": "Taxas para simulacao. Se omitido, usa hierarquia de taxas." }, "taxes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Taxes", "description": "Alias para 'fees' (backward compat)" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id", "description": "ID do produto financeiro (opaco, definido pelo Backoffice). Filtra a policy de taxa por produto.", "examples": [ "b3f1c2a4-5d6e-7f80-9a1b-2c3d4e5f6a7b" ] }, "policy_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy Id", "description": "ID da policy do originador (override). Se informado, substitui a policy principal na resolucao.", "examples": [ "01970dc5-1234-7000-8000-000000000000" ] }, "requested_advance_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" } ], "title": "Requested Advance Value", "description": "[DEPRECATED — use `requested_net_future_value`] Obrigatorio e VALIDADO com o MESMO criterio do `request-anticipation` (veredito simulado = veredito do request): deve ser EXATAMENTE igual a soma do Net Future Value (`net_future_value`) dos itens em `stock_item_ids`; qualquer outro valor => `422` com `detail.code` `STOCK_REQUESTED_VALUE_MISMATCH`. A simulacao considera sempre 100% dos itens, com desagio sobre o NFV de cada um. Para fixar o liquido alvo use `fees.total_liquid_value_brl`. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "stock_item_ids", "requested_advance_value" ], "title": "SimulateAnticipationFromStock" }, "SimulatedReceivable": { "properties": { "external_id": { "type": "string", "title": "External Id" }, "identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Identifier" }, "payer_name": { "type": "string", "title": "Payer Name" }, "payer_document": { "type": "string", "title": "Payer Document" }, "due_date": { "type": "string", "title": "Due Date" }, "gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do lastro (R$). Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica)." }, "net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Future Value", "description": "Net Future Value do recebivel — lastro FUTURO liquido dos descontos ja aplicados a ele. Nome CANONICO publico; equivale EXATAMENTE a `net_face_value` (mesmo numero, mesma semantica)." }, "requested_net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Requested Net Future Value", "description": "Valor ABSOLUTO antecipado deste recebivel (R$). Nome CANONICO publico; equivale EXATAMENTE a `requested_advance_value` (mesmo numero, mesma semantica)." }, "present_value_discount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Present Value Discount", "description": "Desconto total cumulativo (R$) — a diferenca entre o valor FUTURO antecipado e o valor PRESENTE pago. Nome CANONICO publico; equivale EXATAMENTE a `discounted_value` (mesmo numero, mesma semantica)." }, "net_present_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Present Liquid Value", "description": "Valor liquido (PRESENTE) do recebivel (R$). Nome CANONICO publico; equivale EXATAMENTE a `liquid_value` (mesmo numero, mesma semantica)." }, "days_advanced": { "type": "integer", "title": "Days Advanced" }, "monthly_rate_pct": { "type": "string", "title": "Monthly Rate Pct", "description": "Taxa mensal aplicada (%)" }, "discount_pct": { "type": "string", "title": "Discount Pct", "description": "Desagio fixo aplicado (%)" }, "fixed_discount_brl": { "type": "string", "title": "Fixed Discount Brl", "description": "Desconto fixo aplicado (R$)" }, "floating_days": { "type": "integer", "title": "Floating Days" }, "fee_source": { "title": "Fee Source", "description": "Origem da taxa aplicada a ESTE recebivel: a camada da hierarquia que a forneceu, ou o motivo do override quando o liquido foi fixado.", "$ref": "#/components/schemas/FeeSource" }, "requested_advance_value": { "type": "string", "title": "Requested Advance Value", "description": "[DEPRECATED — use `requested_net_future_value`] Valor ABSOLUTO antecipado deste recebivel (R$). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "net_face_value": { "type": "string", "title": "Net Face Value", "description": "[DEPRECATED — use `net_future_value`] Net Future Value do recebivel — lastro FUTURO liquido dos descontos ja aplicados a ele. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "gross_face_value": { "type": "string", "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do lastro (R$). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "discounted_value": { "type": "string", "title": "Discounted Value", "description": "[DEPRECATED — use `present_value_discount`] Desconto total cumulativo (R$) — a diferenca entre o valor FUTURO antecipado e o valor PRESENTE pago. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "liquid_value": { "type": "string", "title": "Liquid Value", "description": "[DEPRECATED — use `net_present_liquid_value`] Valor liquido (PRESENTE) do recebivel (R$). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "external_id", "identifier", "payer_name", "payer_document", "requested_advance_value", "net_face_value", "gross_face_value", "due_date", "days_advanced", "monthly_rate_pct", "discount_pct", "fixed_discount_brl", "floating_days", "discounted_value", "liquid_value", "fee_source" ], "title": "SimulatedReceivable" }, "SimulationFees": { "properties": { "monthly_rate_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Monthly Rate Pct", "description": "Taxa mensal (%), pro-rata dias. Cumulativa. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 3.5 ] }, "discount_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Discount Pct", "description": "Desagio fixo (%) sobre valor. Cumulativa. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 2.0 ] }, "fixed_discount_brl": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Fixed Discount Brl", "description": "Desconto nominal fixo em reais por recebivel. Cumulativo. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 150.0 ] }, "floating_days": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Floating Days", "description": "Dias de floating SOMADOS ao prazo cobrado no desagio pro-rata (monthly_rate_pct). Ex.: 25 dias ate o vencimento + 2 de floating => 27 dias cobrados.", "examples": [ 2 ] }, "total_liquid_value_brl": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Total Liquid Value Brl", "description": "Valor liquido total desejado para toda a simulacao. Mutuamente exclusivo com fees." } }, "type": "object", "title": "SimulationFees" }, "SimulationReceivable": { "properties": { "external_id": { "type": "string", "title": "External Id", "description": "Identificador unico do recebivel (ex: numero da NF)", "examples": [ "NF-2026-001" ] }, "identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Identifier", "description": "Identificador interno opcional", "examples": [ "REC001" ] }, "payer_name": { "type": "string", "title": "Payer Name", "description": "Nome ou razao social do sacado (devedor)", "examples": [ "Cliente XPTO Ltda" ] }, "payer_document": { "type": "string", "title": "Payer Document", "description": "CPF (11 digitos) ou CNPJ (14 digitos) do sacado", "examples": [ "98765432000198" ] }, "due_date": { "type": "string", "title": "Due Date", "description": "Data de vencimento do recebivel (YYYY-MM-DD)", "examples": [ "2026-08-15" ] }, "gross_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do lastro (NF antes dos descontos aplicados a ela). Opcional. Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica). ATENCAO — nao e substituicao 1:1 do nome deprecado: usar este campo EXIGE `gross_future_value_deductions` no mesmo payload (envie `0` se nao houver deducoes), senao 422 `DEDUCTIONS_REQUIRED_WITH_GROSS`. O nome deprecado segue aceito sozinho.", "examples": [ 12000.0 ] }, "gross_future_value_deductions": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Gross Future Value Deductions", "description": "Descontos ja aplicados ao lastro, DECLARADOS: `gross_future_value - net_future_value`. Informacao gerencial — NAO entra no calculo do desagio. Obrigatorio quando `gross_future_value` e informado (envie `0` para 'sem deducoes'); vindo os tres valores, a decomposicao tem que fechar EXATAMENTE, senao 422 `VALUE_DECOMPOSITION_MISMATCH`.", "examples": [ 2000.0 ] }, "net_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Net Future Value", "description": "Net Future Value do recebivel — valor de face FUTURO, LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros). Teto da antecipacao. Nome CANONICO publico; equivale EXATAMENTE a `net_face_value` (mesmo numero, mesma semantica).", "examples": [ 10000.0 ] }, "requested_net_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Requested Net Future Value", "description": "Quanto do Net Future Value se antecipa (BRL, valor ABSOLUTO; o equivalente percentual e `requested_net_future_value_percent`). Se menor que o NFV, antecipacao PARCIAL. A simulacao nao cria o item-resto: o remainder no estoque nasce em `POST /v1/operations/direct`. Nome CANONICO publico; equivale EXATAMENTE a `requested_advance_value` (mesmo numero, mesma semantica).", "examples": [ 10000.0 ] }, "requested_net_future_value_percent": { "anyOf": [ { "type": "number", "maximum": 100.0, "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,3}|(?=[\\d.]{1,6}0*$)\\d{0,3}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Requested Net Future Value Percent", "description": "Percentual do Net Future Value a antecipar (0 < valor <= 100). MUTUAMENTE EXCLUSIVO com `requested_net_future_value` e `requested_advance_value` (=> 422 `REQUESTED_VALUE_AMBIGUOUS`). Resolucao: `percent / 100 * net_future_value`, arredondado a centavos SEMPRE PARA BAIXO; `100` devolve o NFV EXATO. Mesmo criterio do `POST /v1/operations/direct` — veredito simulado = veredito do request.", "examples": [ 60.0 ] }, "monthly_rate_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Monthly Rate Pct", "description": "Taxa mensal (%), pro-rata dias. Cumulativa. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 3.5 ] }, "discount_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Discount Pct", "description": "Desagio fixo (%) sobre valor, independente do prazo. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 2.0 ] }, "fixed_discount_brl": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Fixed Discount Brl", "description": "Desconto nominal fixo em reais. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`.", "examples": [ 500.0 ] }, "liquid_value_brl": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Liquid Value Brl", "description": "Valor liquido desejado. Mutuamente exclusivo com fees.", "examples": [ 9500.0 ] }, "gross_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do lastro (NF antes dos descontos aplicados a ela). Opcional. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico.", "examples": [ 12000.0 ] }, "net_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" } ], "title": "Net Face Value", "description": "[DEPRECATED — use `net_future_value`] Net Future Value do recebivel — valor de face FUTURO, LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros). Teto da antecipacao. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico.", "examples": [ 10000.0 ] }, "requested_advance_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" } ], "title": "Requested Advance Value", "description": "[DEPRECATED — use `requested_net_future_value`] Quanto do Net Future Value se antecipa (BRL, valor ABSOLUTO; o equivalente percentual e `requested_net_future_value_percent`). Se menor que o NFV, antecipacao PARCIAL. A simulacao nao cria o item-resto: o remainder no estoque nasce em `POST /v1/operations/direct`. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico.", "examples": [ 10000.0 ] } }, "type": "object", "required": [ "external_id", "payer_name", "payer_document", "net_face_value", "requested_advance_value", "due_date" ], "title": "SimulationReceivable" }, "SimulationRequest": { "properties": { "assignor_document": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Document", "description": "CPF ou CNPJ do cedente (opcional). Se informado, o sistema busca a policy ativa para esse cedente e aplica na hierarquia (nivel 3).", "examples": [ "12345678000195" ] }, "receivables": { "items": { "$ref": "#/components/schemas/SimulationReceivable" }, "type": "array", "minItems": 1, "title": "Receivables", "description": "Lista de recebiveis para simular" }, "fees": { "anyOf": [ { "$ref": "#/components/schemas/SimulationFees" }, { "type": "null" } ], "description": "Taxas customizadas. Se null, usa taxas da policy." }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id", "description": "ID do produto (opaco, definido pelo BO). Filtra policies por produto." }, "policy_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policy Id", "description": "ID da policy do originador (override). Se informado, substitui a policy principal." }, "taxes": { "anyOf": [ { "$ref": "#/components/schemas/SimulationFees" }, { "type": "null" } ] } }, "type": "object", "required": [ "receivables" ], "title": "SimulationRequest" }, "SimulationResponse": { "properties": { "id": { "type": "string", "title": "Id", "default": "simulation" }, "status": { "type": "string", "title": "Status", "default": "SIMULATED" }, "opr_gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Future Value", "description": "Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Nome CANONICO publico; equivale EXATAMENTE a `opr_gross_face_value` (mesmo numero, mesma semantica)." }, "opr_net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Future Value", "description": "Net Face Value (NFV) agregado da operacao — a soma do `net_face_value` dos recebiveis, ou seja o valor de face FUTURO LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros). MESMA agregacao nas 4 portas (`/v1/operations/direct`, `/v1/simulate`, `/v1/stock/request-anticipation`, `/v1/stock/simulate-anticipation`). Numa antecipacao PARCIAL pelo fluxo direto este campo reporta o NFV INTEIRO, nao o valor antecipado — a base do desagio dessa operacao e a soma de `requested_advance_value` item a item, disponivel em `receivables[]`. No fluxo de ESTOQUE este campo E a base do desagio (100% dos itens). Nome CANONICO publico; equivale EXATAMENTE a `opr_net_face_value` (mesmo numero, mesma semantica)." }, "opr_present_value_discount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Present Value Discount", "description": "Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Nome CANONICO publico; equivale EXATAMENTE a `opr_discounted_value` (mesmo numero, mesma semantica)." }, "opr_net_present_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Present Liquid Value", "description": "Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Nome CANONICO publico; equivale EXATAMENTE a `opr_liquid_value` (mesmo numero, mesma semantica)." }, "average_days_in_advance": { "type": "integer", "title": "Average Days In Advance" }, "weighted_avg_days": { "type": "integer", "title": "Weighted Avg Days", "description": "Prazo medio ponderado (PMP) da operacao em dias" }, "fee_hierarchy": { "type": "string", "title": "Fee Hierarchy" }, "assignor_defaults_used": { "type": "boolean", "title": "Assignor Defaults Used", "description": "Se policy/defaults do cedente foram encontrados" }, "payer_defaults_used": { "type": "boolean", "title": "Payer Defaults Used", "description": "Se policy/defaults de algum sacado foram encontrados" }, "policy_used": { "anyOf": [ { "$ref": "#/components/schemas/PolicyUsedResponse" }, { "type": "null" } ], "description": "Detalhes da policy que forneceu as taxas predominantes" }, "receivables": { "items": { "$ref": "#/components/schemas/SimulatedReceivable" }, "type": "array", "title": "Receivables" }, "opr_gross_face_value": { "type": "string", "title": "Opr Gross Face Value", "description": "[DEPRECATED — use `opr_gross_future_value`] Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_net_face_value": { "type": "string", "title": "Opr Net Face Value", "description": "[DEPRECATED — use `opr_net_future_value`] Net Face Value (NFV) agregado da operacao — a soma do `net_face_value` dos recebiveis, ou seja o valor de face FUTURO LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros). MESMA agregacao nas 4 portas (`/v1/operations/direct`, `/v1/simulate`, `/v1/stock/request-anticipation`, `/v1/stock/simulate-anticipation`). Numa antecipacao PARCIAL pelo fluxo direto este campo reporta o NFV INTEIRO, nao o valor antecipado — a base do desagio dessa operacao e a soma de `requested_advance_value` item a item, disponivel em `receivables[]`. No fluxo de ESTOQUE este campo E a base do desagio (100% dos itens). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_discounted_value": { "type": "string", "title": "Opr Discounted Value", "description": "[DEPRECATED — use `opr_present_value_discount`] Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_liquid_value": { "type": "string", "title": "Opr Liquid Value", "description": "[DEPRECATED — use `opr_net_present_liquid_value`] Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "opr_gross_face_value", "opr_net_face_value", "opr_discounted_value", "opr_liquid_value", "average_days_in_advance", "weighted_avg_days", "fee_hierarchy", "assignor_defaults_used", "payer_defaults_used", "receivables" ], "title": "SimulationResponse" }, "StockAnticipationFees": { "properties": { "monthly_rate_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Monthly Rate Pct", "description": "Taxa mensal (%), pro-rata dias. Cumulativa. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`." }, "discount_pct": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Discount Pct", "description": "Desagio fixo (%) sobre valor. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`." }, "fixed_discount_brl": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Fixed Discount Brl", "description": "Desconto nominal fixo em reais. **Nao aceita valor negativo** (422 de validacao): nenhuma das 3 modalidades e credito ao cedente. O calculo do desagio ignora parcela <= 0, entao um valor negativo produziria desagio ZERO — com a aparencia de taxa configurada. Taxa zero DELIBERADA se escreve `0`." }, "floating_days": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Floating Days", "description": "Dias de floating SOMADOS ao prazo cobrado no desagio pro-rata. Ex.: 25 dias + 2 floating => 27 dias cobrados." }, "total_liquid_value_brl": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Total Liquid Value Brl", "description": "Valor liquido total desejado. Mutuamente exclusivo com fees." } }, "type": "object", "title": "StockAnticipationFees", "description": "Taxas para antecipacao do estoque (mesma logica do operations/direct)." }, "StockBankData": { "properties": { "use_document_pix": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Document Pix", "description": "Pagamento via PIX em chave PIX do CPF/CNPJ do cedente" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code", "description": "Codigo do banco (3 digitos)" }, "agency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agency", "description": "Agencia" }, "account": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account", "description": "Numero da conta com digito" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "Tipo da conta: `CC` (corrente), `CP` (poupanca) ou `SA` (salario). NAO validado hoje — outro valor e aceito e gravado como veio." } }, "type": "object", "title": "StockBankData", "description": "Dados de pagamento — obrigatorio em antecipacao." }, "StockItemCreate": { "properties": { "assignor_id": { "type": "string", "format": "uuid", "title": "Assignor Id" }, "payer_id": { "type": "string", "format": "uuid", "title": "Payer Id" }, "external_id": { "type": "string", "maxLength": 80, "minLength": 1, "title": "External Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "backing_type": { "anyOf": [ { "$ref": "#/components/schemas/ReceivableBackingType" }, { "type": "null" } ], "title": "Backing Type", "default": "NFE" }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "gross_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do lastro (antes dos descontos aplicados a ele). NAO e a base do desagio — a base do fluxo de estoque e o Net Future Value (`net_future_value`). E a grandeza dos LIMITES agregados de exposicao e do cap de valor do token, e o teto do proprio NFV (NFV maior que este valor => 422). Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica). ATENCAO — nao e substituicao 1:1 do nome deprecado: usar este campo EXIGE `gross_future_value_deductions` no mesmo payload (envie `0` se nao houver deducoes), senao 422 `DEDUCTIONS_REQUIRED_WITH_GROSS`. O nome deprecado segue aceito sozinho." }, "gross_future_value_deductions": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Gross Future Value Deductions", "description": "Descontos ja aplicados ao lastro, DECLARADOS: `gross_future_value - net_future_value`. Informacao gerencial — NAO entra no calculo do desagio. Obrigatorio quando `gross_future_value` e informado (envie `0` para declarar 'sem deducoes'); vindo os tres valores, a decomposicao tem que fechar EXATAMENTE, senao 422 `VALUE_DECOMPOSITION_MISMATCH`." }, "net_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Net Future Value", "description": "Net Future Value do lastro — valor de face FUTURO, LIQUIDO dos descontos ja aplicados a ele (impostos na fonte ou outros). E o que a operacao agrega em `opr_net_future_value`, o que o saldo do estoque soma e a BASE DO DESAGIO do fluxo de estoque. A diferenca `gross_future_value - net_future_value` e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro) e NAO entra no calculo do desagio. Obrigatorio e `> 0` — mesma regra de `POST /v1/operations/direct`. Nome CANONICO publico; equivale EXATAMENTE a `net_face_value` (mesmo numero, mesma semantica)." }, "pre_authorized": { "type": "boolean", "title": "Pre Authorized", "description": "Indica se o recebivel ja esta pre-autorizado para antecipacao" }, "nfe_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfe Number" }, "nfe_serie": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfe Serie" }, "nfe_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfe Key" }, "nfe_issue_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Nfe Issue Date" }, "nfe_total_value": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Nfe Total Value" }, "gross_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" } ], "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do lastro (antes dos descontos aplicados a ele). NAO e a base do desagio — a base do fluxo de estoque e o Net Future Value (`net_future_value`). E a grandeza dos LIMITES agregados de exposicao e do cap de valor do token, e o teto do proprio NFV (NFV maior que este valor => 422). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "net_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" } ], "title": "Net Face Value", "description": "[DEPRECATED — use `net_future_value`] Net Future Value do lastro — valor de face FUTURO, LIQUIDO dos descontos ja aplicados a ele (impostos na fonte ou outros). E o que a operacao agrega em `opr_net_future_value`, o que o saldo do estoque soma e a BASE DO DESAGIO do fluxo de estoque. A diferenca `gross_future_value - net_future_value` e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro) e NAO entra no calculo do desagio. Obrigatorio e `> 0` — mesma regra de `POST /v1/operations/direct`. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "assignor_id", "payer_id", "external_id", "gross_face_value", "net_face_value", "due_date", "pre_authorized" ], "title": "StockItemCreate" }, "StockItemCreateResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "external_id": { "type": "string", "title": "External Id" }, "status": { "title": "Status", "$ref": "#/components/schemas/ReceivableStockStatus" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "external_id", "status", "created_at" ], "title": "StockItemCreateResponse" }, "StockItemDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "external_id": { "type": "string", "title": "External Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "backing_type": { "title": "Backing Type", "$ref": "#/components/schemas/ReceivableBackingType" }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do item de estoque. Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica)." }, "net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Future Value", "description": "Net Future Value do item — valor de face futuro LIQUIDO dos descontos ja aplicados ao lastro. E a BASE DO DESAGIO do fluxo de estoque e o que o saldo do estoque soma. Nome CANONICO publico; equivale EXATAMENTE a `net_face_value` (mesmo numero, mesma semantica)." }, "pre_authorized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pre Authorized" }, "status": { "title": "Status", "$ref": "#/components/schemas/ReceivableStockStatus" }, "assignor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" }, "payer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payer Id" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "originator_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Originator Id" }, "internal_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Internal Identifier" }, "nfe_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfe Number" }, "nfe_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfe Key" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "locked_by_proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Locked By Proposal Id" }, "consumed_by_operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Consumed By Operation Id" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "gross_face_value": { "type": "string", "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do item de estoque. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Face Value", "description": "[DEPRECATED — use `net_future_value`] Net Future Value do item — valor de face futuro LIQUIDO dos descontos ja aplicados ao lastro. E a BASE DO DESAGIO do fluxo de estoque e o que o saldo do estoque soma. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "id", "external_id", "backing_type", "gross_face_value", "due_date", "status" ], "title": "StockItemDetail" }, "StockItemStatusResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "title": "Status", "$ref": "#/components/schemas/ReceivableStockStatus" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "status" ], "title": "StockItemStatusResponse" }, "StockItemSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "external_id": { "type": "string", "title": "External Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "backing_type": { "title": "Backing Type", "$ref": "#/components/schemas/ReceivableBackingType" }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do item de estoque. Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica)." }, "net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Future Value", "description": "Net Future Value do item — valor de face futuro LIQUIDO dos descontos ja aplicados ao lastro. E a BASE DO DESAGIO do fluxo de estoque e o que o saldo do estoque soma. Nome CANONICO publico; equivale EXATAMENTE a `net_face_value` (mesmo numero, mesma semantica)." }, "pre_authorized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pre Authorized" }, "status": { "title": "Status", "$ref": "#/components/schemas/ReceivableStockStatus" }, "assignor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" }, "payer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payer Id" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "gross_face_value": { "type": "string", "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do item de estoque. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Face Value", "description": "[DEPRECATED — use `net_future_value`] Net Future Value do item — valor de face futuro LIQUIDO dos descontos ja aplicados ao lastro. E a BASE DO DESAGIO do fluxo de estoque e o que o saldo do estoque soma. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "id", "external_id", "backing_type", "gross_face_value", "due_date", "status" ], "title": "StockItemSummary" }, "StockItemUpdate": { "properties": { "assignor_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Assignor Id" }, "payer_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Payer Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "backing_type": { "anyOf": [ { "$ref": "#/components/schemas/ReceivableBackingType" }, { "type": "null" } ], "title": "Backing Type" }, "due_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Due Date" }, "gross_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do lastro (antes dos descontos aplicados a ele). Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica). ATENCAO — nao e substituicao 1:1 do nome deprecado: usar este campo EXIGE `gross_future_value_deductions` no mesmo payload (envie `0` se nao houver deducoes), senao 422 `DEDUCTIONS_REQUIRED_WITH_GROSS`. O nome deprecado segue aceito sozinho." }, "gross_future_value_deductions": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Gross Future Value Deductions", "description": "Descontos ja aplicados ao lastro, DECLARADOS: `gross_future_value - net_future_value`. Informacao gerencial — NAO entra no calculo do desagio. Obrigatorio quando `gross_future_value` e informado (envie `0` para declarar 'sem deducoes'); vindo os tres valores, a decomposicao tem que fechar EXATAMENTE, senao 422 `VALUE_DECOMPOSITION_MISMATCH`." }, "net_future_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Net Future Value", "description": "Net Future Value do lastro — valor de face futuro, LIQUIDO dos descontos ja aplicados a ele. Alimenta `opr_net_future_value`, o saldo do estoque e e a BASE DO DESAGIO do fluxo de estoque (ver a descricao do mesmo campo em `POST /v1/stock`). Se enviado, deve ser `> 0` — mesma regra do create (o PATCH nao afrouxa o que a criacao exige). Nome CANONICO publico; equivale EXATAMENTE a `net_face_value` (mesmo numero, mesma semantica)." }, "pre_authorized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pre Authorized" }, "nfe_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfe Number" }, "nfe_serie": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfe Serie" }, "nfe_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfe Key" }, "nfe_issue_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Nfe Issue Date" }, "nfe_total_value": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Nfe Total Value" }, "gross_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do lastro (antes dos descontos aplicados a ele). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "net_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*(?:\\d{0,16}|(?=[\\d.]{1,19}0*$)\\d{0,16}\\.\\d{0,2}0*$)" }, { "type": "null" } ], "title": "Net Face Value", "description": "[DEPRECATED — use `net_future_value`] Net Future Value do lastro — valor de face futuro, LIQUIDO dos descontos ja aplicados a ele. Alimenta `opr_net_future_value`, o saldo do estoque e e a BASE DO DESAGIO do fluxo de estoque (ver a descricao do mesmo campo em `POST /v1/stock`). Se enviado, deve ser `> 0` — mesma regra do create (o PATCH nao afrouxa o que a criacao exige). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "title": "StockItemUpdate", "description": "Campos editaveis de um item do estoque. Todos opcionais — enviar apenas o que alterar." }, "StockListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/StockItemSummary" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "items", "total" ], "title": "StockListResponse" }, "StockSimulatedReceivable": { "properties": { "stock_item_id": { "type": "string", "title": "Stock Item Id" }, "external_id": { "type": "string", "title": "External Id" }, "due_date": { "type": "string", "title": "Due Date" }, "gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do item de estoque. NAO e a base do desagio: a base deste fluxo e o Net Future Value. A diferenca entre os dois e informacao gerencial (descontos ja aplicados ao lastro). Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica)." }, "net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Future Value", "description": "Net Future Value do item — valor de face futuro LIQUIDO dos descontos aplicados ao lastro. E o valor-base do desagio deste recebivel no fluxo de estoque. Nome CANONICO publico; equivale EXATAMENTE a `net_face_value` (mesmo numero, mesma semantica)." }, "requested_net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Requested Net Future Value", "description": "Valor solicitado no cadastro do item. ECO do estoque — a simulacao a partir do estoque calcula o desagio sobre o Net Future Value, nao sobre este campo. O fluxo de estoque antecipa sempre 100% do item selecionado; antecipacao PARCIAL so existe em `POST /v1/operations/direct`. Nome CANONICO publico; equivale EXATAMENTE a `requested_advance_value` (mesmo numero, mesma semantica)." }, "present_value_discount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Present Value Discount", "description": "Desagio cobrado neste recebivel, em BRL. Nome CANONICO publico; equivale EXATAMENTE a `discount_brl` (mesmo numero, mesma semantica)." }, "net_present_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Present Liquid Value", "description": "Valor liquido deste recebivel = Net Future Value (a base do desagio no fluxo de estoque) menos o desagio. Nome CANONICO publico; equivale EXATAMENTE a `liquid_value` (mesmo numero, mesma semantica)." }, "days_advanced": { "type": "integer", "title": "Days Advanced", "description": "Dias efetivamente COBRADOS no desagio deste recebivel = dias ate o vencimento + `floating_days`. Nao confundir com `qty_days_advanced` do titulo criado, que exclui o floating." }, "monthly_rate_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Monthly Rate Pct" }, "discount_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Discount Pct" }, "fixed_discount_brl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fixed Discount Brl" }, "fee_source": { "anyOf": [ { "$ref": "#/components/schemas/StockFeeSource" }, { "type": "null" } ], "title": "Fee Source" }, "gross_face_value": { "type": "string", "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do item de estoque. NAO e a base do desagio: a base deste fluxo e o Net Future Value. A diferenca entre os dois e informacao gerencial (descontos ja aplicados ao lastro). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Face Value", "description": "[DEPRECATED — use `net_future_value`] Net Future Value do item — valor de face futuro LIQUIDO dos descontos aplicados ao lastro. E o valor-base do desagio deste recebivel no fluxo de estoque. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "requested_advance_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Requested Advance Value", "description": "[DEPRECATED — use `requested_net_future_value`] Valor solicitado no cadastro do item. ECO do estoque — a simulacao a partir do estoque calcula o desagio sobre o Net Future Value, nao sobre este campo. O fluxo de estoque antecipa sempre 100% do item selecionado; antecipacao PARCIAL so existe em `POST /v1/operations/direct`. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "discount_brl": { "type": "string", "title": "Discount Brl", "description": "[DEPRECATED — use `present_value_discount`] Desagio cobrado neste recebivel, em BRL. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "liquid_value": { "type": "string", "title": "Liquid Value", "description": "[DEPRECATED — use `net_present_liquid_value`] Valor liquido deste recebivel = Net Future Value (a base do desagio no fluxo de estoque) menos o desagio. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "additionalProperties": true, "type": "object", "required": [ "stock_item_id", "external_id", "gross_face_value", "due_date", "days_advanced", "discount_brl", "liquid_value" ], "title": "StockSimulatedReceivable", "description": "Item simulado de uma antecipacao a partir do estoque." }, "StockSimulationResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "opr_gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Future Value", "description": "Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Nome CANONICO publico; equivale EXATAMENTE a `opr_gross_face_value` (mesmo numero, mesma semantica)." }, "opr_net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Future Value", "description": "Net Face Value (NFV) agregado da operacao — a soma do `net_face_value` dos recebiveis, ou seja o valor de face FUTURO LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros). MESMA agregacao nas 4 portas (`/v1/operations/direct`, `/v1/simulate`, `/v1/stock/request-anticipation`, `/v1/stock/simulate-anticipation`). Numa antecipacao PARCIAL pelo fluxo direto este campo reporta o NFV INTEIRO, nao o valor antecipado — a base do desagio dessa operacao e a soma de `requested_advance_value` item a item, disponivel em `receivables[]`. No fluxo de ESTOQUE este campo E a base do desagio (100% dos itens). Nome CANONICO publico; equivale EXATAMENTE a `opr_net_face_value` (mesmo numero, mesma semantica)." }, "opr_present_value_discount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Present Value Discount", "description": "Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Nome CANONICO publico; equivale EXATAMENTE a `opr_discounted_value` (mesmo numero, mesma semantica)." }, "opr_net_present_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Present Liquid Value", "description": "Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Nome CANONICO publico; equivale EXATAMENTE a `opr_liquid_value` (mesmo numero, mesma semantica)." }, "average_days_in_advance": { "type": "integer", "title": "Average Days In Advance", "description": "Prazo medio simples da operacao, em dias: media aritmetica TRUNCADA dos dias ate o vencimento dos recebiveis. Nao e ponderada por valor e NAO inclui `floating_days`." }, "floating_days": { "type": "integer", "title": "Floating Days", "description": "Dias de floating aplicados, SOMADOS ao prazo ate o vencimento para formar os dias cobrados no desagio (ex.: 25 dias de prazo + 2 de floating = 27 dias cobrados). O float e custo do funder, nao carencia do cedente." }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id" }, "receivables": { "items": { "$ref": "#/components/schemas/StockSimulatedReceivable" }, "type": "array", "title": "Receivables" }, "opr_gross_face_value": { "type": "string", "title": "Opr Gross Face Value", "description": "[DEPRECATED — use `opr_gross_future_value`] Valor de face BRUTO somado dos recebiveis da operacao (valor nominal das NF-e/duplicatas, ANTES dos descontos aplicados ao lastro). Descontado dos descontos vira o Net Face Value (`net_face_value`). NAO e base de calculo em nenhuma porta: a diferenca bruto menos NFV e informacao GERENCIAL (impostos na fonte ou outros descontos do lastro). E a grandeza dos LIMITES AGREGADOS de exposicao nos recortes `policy_total`, `policy_entity_default` e `assignor` (403 `LIMIT_AGGREGATE_EXPOSURE`, sob `LIMITS_RESOLUTION=aggregate_max`); o recorte do SACADO usa `requested_advance_value` nas DUAS portas — ou seja, mede o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto. Nao e o valor pago ao cedente. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_net_face_value": { "type": "string", "title": "Opr Net Face Value", "description": "[DEPRECATED — use `opr_net_future_value`] Net Face Value (NFV) agregado da operacao — a soma do `net_face_value` dos recebiveis, ou seja o valor de face FUTURO LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros). MESMA agregacao nas 4 portas (`/v1/operations/direct`, `/v1/simulate`, `/v1/stock/request-anticipation`, `/v1/stock/simulate-anticipation`). Numa antecipacao PARCIAL pelo fluxo direto este campo reporta o NFV INTEIRO, nao o valor antecipado — a base do desagio dessa operacao e a soma de `requested_advance_value` item a item, disponivel em `receivables[]`. No fluxo de ESTOQUE este campo E a base do desagio (100% dos itens). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_discounted_value": { "type": "string", "title": "Opr Discounted Value", "description": "[DEPRECATED — use `opr_present_value_discount`] Desagio TOTAL cobrado na operacao (soma do desconto de cada recebivel): taxa mensal pro-rata sobre os dias cobrados (dias ate o vencimento + `floating_days`, juros simples base 30) + desagio percentual fixo (`discount_pct`) + desconto nominal (`fixed_discount_brl`). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "opr_liquid_value": { "type": "string", "title": "Opr Liquid Value", "description": "[DEPRECATED — use `opr_net_present_liquid_value`] Valor LIQUIDO da operacao = base do desagio menos `opr_discounted_value`. E o montante efetivamente transferido por PIX ao cedente na liquidacao — o funding exige match exato com este valor. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "additionalProperties": true, "type": "object", "required": [ "status", "opr_gross_face_value", "opr_net_face_value", "opr_discounted_value", "opr_liquid_value", "average_days_in_advance", "floating_days", "receivables" ], "title": "StockSimulationResponse", "description": "Resposta de `POST /v1/stock/simulate-anticipation` (read-only)." }, "TitleDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "operation_id": { "type": "string", "title": "Operation Id" }, "external_id": { "type": "string", "title": "External Id" }, "backing_type": { "title": "Backing Type", "$ref": "#/components/schemas/ReceivableBackingType" }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do recebivel (valor nominal da NF-e/duplicata, antes de deducoes). Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica)." }, "net_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Future Value", "description": "Net Future Value do recebivel — valor de face futuro LIQUIDO dos descontos aplicados ao lastro (impostos na fonte ou outros). E o TETO do antecipavel nas duas portas: o fluxo DIRETO recusa `requested_advance_value > net_face_value` com 422, e o fluxo de ESTOQUE calcula o desagio SOBRE este valor (100% do NFV). No estoque o titulo nasce com `requested_advance_value` IGUAL a este campo — a porta antecipa 100% do Net Future Value —, entao `requested_advance_value - discounted_value` e `net_face_value - discounted_value` dao o MESMO numero. O valor de face BRUTO da NF-e continua disponivel, intacto, em `gross_face_value`. Nome CANONICO publico; equivale EXATAMENTE a `net_face_value` (mesmo numero, mesma semantica)." }, "present_value_discount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Present Value Discount", "description": "Desagio cobrado neste titulo (taxa mensal pro-rata sobre os dias cobrados + desagio percentual + desconto fixo). Nome CANONICO publico; equivale EXATAMENTE a `discounted_value` (mesmo numero, mesma semantica)." }, "net_present_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Present Liquid Value", "description": "Valor liquido deste titulo: a BASE do desagio menos o desagio (`discounted_value`). Gravado tambem como `principal_value_brl`, base do saldo devedor. A subtracao `requested_advance_value - discounted_value` FECHA nas duas portas: no fluxo DIRETO o `requested_advance_value` e o valor solicitado (base do desagio) e no fluxo de ESTOQUE ele e o proprio `net_face_value` (a porta antecipa 100% do Net Future Value, que e a base do desagio desse fluxo). Ver `net_face_value` em `GET /v1/titles/{id}`. Nome CANONICO publico; equivale EXATAMENTE a `liquid_value` (mesmo numero, mesma semantica)." }, "status": { "title": "Status", "$ref": "#/components/schemas/TitleStatus" }, "current_outstanding_balance_brl": { "type": "string", "title": "Current Outstanding Balance Brl" }, "cumulative_payment_brl": { "type": "string", "title": "Cumulative Payment Brl" }, "total_returned_value": { "type": "string", "title": "Total Returned Value" }, "payer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payer Id" }, "assignor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "effective_cost_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Effective Cost Pct", "description": "Custo efetivo deste titulo em % do valor antecipado (`discounted_value` / valor antecipado x 100), com 4 casas." }, "applied_monthly_rate_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applied Monthly Rate Pct" }, "applied_discount_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applied Discount Pct" }, "applied_floating_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Applied Floating Days", "description": "Dias de floating aplicados, SOMADOS ao prazo ate o vencimento para formar os dias cobrados no desagio (ex.: 25 dias de prazo + 2 de floating = 27 dias cobrados). O float e custo do funder, nao carencia do cedente." }, "applied_late_fee_pct": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applied Late Fee Pct" }, "applied_default_interest_pct_monthly": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applied Default Interest Pct Monthly" }, "qty_days_advanced": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Qty Days Advanced", "description": "Dias antecipados: dias corridos entre a criacao e o vencimento do recebivel. NAO inclui `applied_floating_days` — os dias efetivamente COBRADOS no desagio sao a soma dos dois." }, "principal_value_brl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Value Brl" }, "accrued_interest_brl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accrued Interest Brl" }, "accrued_late_fee_brl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accrued Late Fee Brl" }, "accrued_default_interest_brl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accrued Default Interest Brl" }, "fully_returned_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Fully Returned At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "gross_face_value": { "type": "string", "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do recebivel (valor nominal da NF-e/duplicata, antes de deducoes). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "liquid_value": { "type": "string", "title": "Liquid Value", "description": "[DEPRECATED — use `net_present_liquid_value`] Valor liquido deste titulo: a BASE do desagio menos o desagio (`discounted_value`). Gravado tambem como `principal_value_brl`, base do saldo devedor. A subtracao `requested_advance_value - discounted_value` FECHA nas duas portas: no fluxo DIRETO o `requested_advance_value` e o valor solicitado (base do desagio) e no fluxo de ESTOQUE ele e o proprio `net_face_value` (a porta antecipa 100% do Net Future Value, que e a base do desagio desse fluxo). Ver `net_face_value` em `GET /v1/titles/{id}`. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Face Value", "description": "[DEPRECATED — use `net_future_value`] Net Future Value do recebivel — valor de face futuro LIQUIDO dos descontos aplicados ao lastro (impostos na fonte ou outros). E o TETO do antecipavel nas duas portas: o fluxo DIRETO recusa `requested_advance_value > net_face_value` com 422, e o fluxo de ESTOQUE calcula o desagio SOBRE este valor (100% do NFV). No estoque o titulo nasce com `requested_advance_value` IGUAL a este campo — a porta antecipa 100% do Net Future Value —, entao `requested_advance_value - discounted_value` e `net_face_value - discounted_value` dao o MESMO numero. O valor de face BRUTO da NF-e continua disponivel, intacto, em `gross_face_value`. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "discounted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Discounted Value", "description": "[DEPRECATED — use `present_value_discount`] Desagio cobrado neste titulo (taxa mensal pro-rata sobre os dias cobrados + desagio percentual + desconto fixo). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "id", "operation_id", "external_id", "backing_type", "gross_face_value", "liquid_value", "due_date", "status", "current_outstanding_balance_brl", "cumulative_payment_brl", "total_returned_value" ], "title": "TitleDetail" }, "TitleListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TitleSummary" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "items", "total" ], "title": "TitleListResponse" }, "TitleSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "operation_id": { "type": "string", "title": "Operation Id" }, "external_id": { "type": "string", "title": "External Id" }, "backing_type": { "title": "Backing Type", "$ref": "#/components/schemas/ReceivableBackingType" }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "gross_future_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gross Future Value", "description": "Valor de face BRUTO do recebivel (valor nominal da NF-e/duplicata, antes de deducoes). Nome CANONICO publico; equivale EXATAMENTE a `gross_face_value` (mesmo numero, mesma semantica)." }, "net_present_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Present Liquid Value", "description": "Valor liquido deste titulo: a BASE do desagio menos o desagio (`discounted_value`). Gravado tambem como `principal_value_brl`, base do saldo devedor. A subtracao `requested_advance_value - discounted_value` FECHA nas duas portas: no fluxo DIRETO o `requested_advance_value` e o valor solicitado (base do desagio) e no fluxo de ESTOQUE ele e o proprio `net_face_value` (a porta antecipa 100% do Net Future Value, que e a base do desagio desse fluxo). Ver `net_face_value` em `GET /v1/titles/{id}`. Nome CANONICO publico; equivale EXATAMENTE a `liquid_value` (mesmo numero, mesma semantica)." }, "status": { "title": "Status", "$ref": "#/components/schemas/TitleStatus" }, "current_outstanding_balance_brl": { "type": "string", "title": "Current Outstanding Balance Brl" }, "cumulative_payment_brl": { "type": "string", "title": "Cumulative Payment Brl" }, "total_returned_value": { "type": "string", "title": "Total Returned Value" }, "payer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payer Id" }, "assignor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignor Id" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "gross_face_value": { "type": "string", "title": "Gross Face Value", "description": "[DEPRECATED — use `gross_future_value`] Valor de face BRUTO do recebivel (valor nominal da NF-e/duplicata, antes de deducoes). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." }, "liquid_value": { "type": "string", "title": "Liquid Value", "description": "[DEPRECATED — use `net_present_liquid_value`] Valor liquido deste titulo: a BASE do desagio menos o desagio (`discounted_value`). Gravado tambem como `principal_value_brl`, base do saldo devedor. A subtracao `requested_advance_value - discounted_value` FECHA nas duas portas: no fluxo DIRETO o `requested_advance_value` e o valor solicitado (base do desagio) e no fluxo de ESTOQUE ele e o proprio `net_face_value` (a porta antecipa 100% do Net Future Value, que e a base do desagio desse fluxo). Ver `net_face_value` em `GET /v1/titles/{id}`. Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "type": "object", "required": [ "id", "operation_id", "external_id", "backing_type", "gross_face_value", "liquid_value", "due_date", "status", "current_outstanding_balance_brl", "cumulative_payment_brl", "total_returned_value" ], "title": "TitleSummary" }, "TokenRequest": { "properties": { "client_id": { "type": "string", "minLength": 5, "title": "Client Id", "description": "Credencial de API: X-Client-Id" }, "client_secret": { "type": "string", "minLength": 8, "title": "Client Secret", "description": "Credencial de API: X-Client-Secret" }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Requested scopes. If omitted, uses all scopes of the credential." } }, "type": "object", "required": [ "client_id", "client_secret" ], "title": "TokenRequest" }, "TokenResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Token lifetime in seconds" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes", "description": "Granted scopes" } }, "type": "object", "required": [ "access_token", "expires_in", "scopes" ], "title": "TokenResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WebhookCreate": { "properties": { "url": { "type": "string", "minLength": 10, "pattern": "^https://", "title": "Url" }, "events": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array", "minItems": 1, "title": "Events" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "required": [ "url", "events" ], "title": "WebhookCreate" }, "WebhookCreateResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "event_types": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array" }, { "type": "null" } ], "title": "Event Types" }, "hmac_secret": { "type": "string", "title": "Hmac Secret" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "url", "hmac_secret" ], "title": "WebhookCreateResponse" }, "WebhookDelivery": { "properties": { "id": { "type": "string", "title": "Id" }, "event_type": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventType" }, { "type": "null" } ], "title": "Event Type" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "response_status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Response Status Code" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Ms" }, "attempt_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Attempt Number" }, "delivered_successfully": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Delivered Successfully" }, "next_retry_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Next Retry At" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id" ], "title": "WebhookDelivery" }, "WebhookDeliveryListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "WebhookDeliveryListResponse" }, "WebhookListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WebhookSummary" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "items", "total" ], "title": "WebhookListResponse" }, "WebhookSubscriptionUpdate": { "properties": { "url": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 10, "pattern": "^https://" }, { "type": "null" } ], "title": "Url" }, "events": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array", "maxItems": 32, "minItems": 1 }, { "type": "null" } ], "title": "Events" }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Description" }, "active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Active" } }, "type": "object", "title": "WebhookSubscriptionUpdate", "description": "Corpo de ``PATCH /v1/webhooks/{id}``. Campos ausentes = inalterados.\n\nNão há campo de segredo: ROTAÇÃO exige uma segunda coluna para janela de\nsobreposição (o consumidor precisa aceitar as duas assinaturas durante o corte) e\nportanto exige migração — está PARQUEADA em\n``alembic/versions_draft/0054_webhooks.py.draft``." }, "WebhookSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "event_types": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array" }, { "type": "null" } ], "title": "Event Types" }, "active": { "type": "boolean", "title": "Active" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "url", "active" ], "title": "WebhookSummary" }, "ValidationErrorDetail": { "properties": { "code": { "type": "string", "const": "validation_error", "title": "Code", "description": "Sempre `validation_error` para falhas de schema." }, "message": { "type": "string", "title": "Message", "description": "Resumo legivel apontando os campos que falharam." }, "errors": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Errors", "description": "Detalhe por campo, um item por falha de validacao." } }, "type": "object", "required": [ "code", "message", "errors" ], "title": "ValidationErrorDetail", "description": "Falha de validacao de schema (corpo/query/path)." }, "StructuredErrorDetail": { "properties": { "code": { "type": "string", "title": "Code", "description": "Codigo do erro de negocio (ex.: `CET_OUT_OF_BOUNDS`)." }, "message": { "type": "string", "title": "Message", "description": "Mensagem legivel do erro." } }, "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "title": "StructuredErrorDetail", "description": "Erro de regra de negocio estruturado. As chaves extras variam por `code` (ex.: `min_pct`/`max_pct` em `CET_OUT_OF_BOUNDS`)." }, "ApiError": { "type": "object", "properties": { "detail": { "anyOf": [ { "$ref": "#/components/schemas/StructuredErrorDetail" }, { "type": "string" } ], "title": "Detail", "description": "Erro estruturado (objeto com `code` + `message` e chaves extras por codigo) ou o codigo do erro como string. As duas formas coexistem no contrato atual — trate `detail` como uniao." } }, "required": [ "detail" ], "title": "ApiError", "description": "Envelope de erro da API. Todo erro de negocio (401/403/404/409/423) chega neste formato; o 429 usa o `RateLimitError` (mesmo envelope, `detail` sempre estruturado) e falhas de SCHEMA usam `HTTPValidationError`." }, "RateLimitError": { "type": "object", "properties": { "detail": { "$ref": "#/components/schemas/StructuredErrorDetail", "description": "Objeto com `code` (`rate_limit_exceeded`), `scope` (`ip` ou `token` — qual bucket negou), `limit_rpm`, `retry_after_seconds` e `message`. O header `Retry-After` traz o mesmo numero de `retry_after_seconds` e e a leitura recomendada." } }, "required": [ "detail" ], "title": "RateLimitError", "description": "Erro de rate limit (429) — UM formato para os dois limites, com `detail.scope` dizendo qual negou. Ver `Retry-After`." }, "OperationLifecycleStatus": { "type": "string", "enum": [ "CREATED", "PRE_APPROVED", "CONTRACT_SENT", "IN_SIGNATURE", "SIGNED", "WAITING_RELEASE", "PROCESSING_PAYMENT", "PAID", "CONTRACT_ERROR", "PAYMENT_ERROR", "DENIED", "CANCELLED", "EXPIRED", "WAITING_APPROVAL", "APPROVED_DIRECT", "COMPLETED" ], "x-extensible-enum": [ "CREATED", "PRE_APPROVED", "CONTRACT_SENT", "IN_SIGNATURE", "SIGNED", "WAITING_RELEASE", "PROCESSING_PAYMENT", "PAID", "CONTRACT_ERROR", "PAYMENT_ERROR", "DENIED", "CANCELLED", "EXPIRED", "WAITING_APPROVAL", "APPROVED_DIRECT", "COMPLETED" ], "title": "OperationLifecycleStatus", "description": "Estado do ciclo de vida da operacao (enum `operation_lifecycle_status`). `WAITING_APPROVAL` aguarda decisao do Backoffice; `APPROVED_DIRECT` foi auto-aprovada dentro do limite; `PAID` teve o PIX enviado ao cedente; `COMPLETED` teve todos os titulos liquidados.\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "OperationReturningStatus": { "type": "string", "enum": [ "NOT_DUE_YET", "WAITING_PAYMENT", "PARTIALLY_RETURNED", "FULLY_RETURNED", "OVERDUE", "OVERDUE_NOTIFIED", "OVERDUE_LEGAL_ACTION" ], "x-extensible-enum": [ "NOT_DUE_YET", "WAITING_PAYMENT", "PARTIALLY_RETURNED", "FULLY_RETURNED", "OVERDUE", "OVERDUE_NOTIFIED", "OVERDUE_LEGAL_ACTION" ], "title": "OperationReturningStatus", "description": "Estagio da VOLTA do capital da operacao (enum `operation_returning_status`) — acompanha o pagamento dos titulos pelo sacado, depois que o cedente ja recebeu.\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "TitleStatus": { "type": "string", "enum": [ "CREATED", "WAITING_PAYMENT", "PAID", "PARTIALLY_PAID", "OVERDUE", "CANCELLED", "WRITTEN_OFF" ], "x-extensible-enum": [ "CREATED", "WAITING_PAYMENT", "PAID", "PARTIALLY_PAID", "OVERDUE", "CANCELLED", "WRITTEN_OFF" ], "title": "TitleStatus", "description": "Estado do titulo (enum `title_status`).\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "ReceivableStockStatus": { "type": "string", "enum": [ "IN_STOCK", "LOCKED", "CONSUMED", "EXPIRED", "CANCELLED" ], "x-extensible-enum": [ "IN_STOCK", "LOCKED", "CONSUMED", "EXPIRED", "CANCELLED" ], "title": "ReceivableStockStatus", "description": "Estado do item no estoque de recebiveis (enum `receivable_stock_status`). `IN_STOCK` esta disponivel; `LOCKED` esta reservado por uma proposta; `CONSUMED` ja virou operacao.\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "ReceivableBackingType": { "type": "string", "enum": [ "NFE", "NFSE", "CTE", "COMMERCIAL_CONTRACT", "COMMERCIAL_NOTE", "SERVICE_ORDER", "DUTY_SHIFT", "TRADE_BILL", "PROMISSORY_NOTE", "PUBLIC_PAYROLL_MARGIN", "PRIVATE_PAYROLL_MARGIN", "SALARY_ADVANCE", "RECURRING_CONTRACT", "UNPERFORMED_CONTRACT", "SIGNED_PURCHASE_ORDER", "DELIVERY_PROOF", "PAYER_ACCEPTANCE_WITH_AGREEMENT", "PAYER_ACCEPTANCE_WITHOUT_AGREEMENT", "BOLETO", "MEASUREMENT_REPORT", "INVOICE", "MEDICAL_CONTRACT", "PRODUCTION_REPORT", "RECEIVABLE_EVIDENCE", "OTHER" ], "x-extensible-enum": [ "NFE", "NFSE", "CTE", "COMMERCIAL_CONTRACT", "COMMERCIAL_NOTE", "SERVICE_ORDER", "DUTY_SHIFT", "TRADE_BILL", "PROMISSORY_NOTE", "PUBLIC_PAYROLL_MARGIN", "PRIVATE_PAYROLL_MARGIN", "SALARY_ADVANCE", "RECURRING_CONTRACT", "UNPERFORMED_CONTRACT", "SIGNED_PURCHASE_ORDER", "DELIVERY_PROOF", "PAYER_ACCEPTANCE_WITH_AGREEMENT", "PAYER_ACCEPTANCE_WITHOUT_AGREEMENT", "BOLETO", "MEASUREMENT_REPORT", "INVOICE", "MEDICAL_CONTRACT", "PRODUCTION_REPORT", "RECEIVABLE_EVIDENCE", "OTHER" ], "title": "ReceivableBackingType", "description": "Tipo de lastro do recebivel (enum `receivable_backing_type`). Valor fora desta lista => 422.\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "BalanceEventType": { "type": "string", "enum": [ "PRINCIPAL_SET", "INTEREST_ACCRUED", "LATE_FEE_APPLIED", "DEFAULT_INTEREST_ACCRUED", "PAYMENT_RECEIVED", "DISCOUNT_GRANTED", "DUE_DATE_EXTENDED", "DUE_DATE_ANTICIPATED", "WRITE_OFF", "MANUAL_ADJUSTMENT", "RECALCULATION", "RESTRUCTURE" ], "x-extensible-enum": [ "PRINCIPAL_SET", "INTEREST_ACCRUED", "LATE_FEE_APPLIED", "DEFAULT_INTEREST_ACCRUED", "PAYMENT_RECEIVED", "DISCOUNT_GRANTED", "DUE_DATE_EXTENDED", "DUE_DATE_ANTICIPATED", "WRITE_OFF", "MANUAL_ADJUSTMENT", "RECALCULATION", "RESTRUCTURE" ], "title": "BalanceEventType", "description": "Tipo do lancamento no extrato de saldo devedor do titulo (enum `balance_event_type`).\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "FeePolicySource": { "type": "string", "enum": [ "assignor", "payer", "policy", "default" ], "x-extensible-enum": [ "assignor", "payer", "policy", "default" ], "title": "FeePolicySource", "description": "Camada que forneceu a POLICY de taxas resolvida. `assignor`, `payer` e `policy` indicam de qual entidade veio a policy; `default` indica que nenhuma policy foi resolvida (a taxa nao veio de policy). NAO inclui `receivable` nem `operation`: quando a taxa vem do payload, este campo permanece em `default`.\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "FeeSource": { "type": "string", "enum": [ "receivable", "operation", "assignor", "payer", "policy", "default", "liquid_value", "total_liquid_value" ], "x-extensible-enum": [ "receivable", "operation", "assignor", "payer", "policy", "default", "liquid_value", "total_liquid_value" ], "title": "FeeSource", "description": "Origem da taxa aplicada a ESTE recebivel. Os seis primeiros valores sao as camadas da hierarquia, na ordem de precedencia: taxa no proprio recebivel > taxa no corpo da operacao > override do cedente > override do sacado > policy do originador > `default` (nenhuma camada definiu o campo). Os dois ultimos sinalizam que a taxa NAO veio da hierarquia porque o integrador fixou o liquido: `liquid_value` (liquido definido por recebivel) e `total_liquid_value` (liquido definido para a operacao inteira e rateado proporcionalmente).\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "StockFeeSource": { "type": "string", "enum": [ "receivable", "operation", "assignor", "payer", "policy", "default", "total_liquid_value" ], "x-extensible-enum": [ "receivable", "operation", "assignor", "payer", "policy", "default", "total_liquid_value" ], "title": "StockFeeSource", "description": "Origem da taxa aplicada a ESTE item do estoque. Igual a `FeeSource` menos `liquid_value`: o fluxo de estoque nao oferece override de liquido por item, apenas `total_liquid_value_brl` para a simulacao inteira.\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "AssignorType": { "type": "string", "enum": [ "NATURAL_PERSON", "LEGAL_ENTITY" ], "x-extensible-enum": [ "NATURAL_PERSON", "LEGAL_ENTITY" ], "title": "AssignorType", "description": "Tipo de pessoa do cedente na grafia PERSISTIDA (enum `assignor_type`). O corpo de `POST /v1/operations/direct` usa a grafia curta `F`/`J`.\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "AssignorDocumentKind": { "type": "string", "enum": [ "F", "J" ], "x-extensible-enum": [ "F", "J" ], "title": "AssignorDocumentKind", "description": "Tipo de pessoa do cedente na grafia do PAYLOAD: `F` (fisica, exige `cpf`) ou `J` (juridica, exige `cnpj`).\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "BankAccountTypePayload": { "type": "string", "enum": [ "CC", "CP", "SA" ], "x-extensible-enum": [ "CC", "CP", "SA" ], "title": "BankAccountTypePayload", "description": "Tipo da conta bancaria na grafia do PAYLOAD: `CC` (corrente), `CP` (poupanca) ou `SA` (salario).\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "TransferMethod": { "type": "string", "enum": [ "PIX", "TED" ], "x-extensible-enum": [ "PIX", "TED" ], "title": "TransferMethod", "description": "Meio de transferencia preferencial do cedente (enum `transfer_method`).\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "DisbursementMethod": { "type": "string", "enum": [ "pix_document", "bank_account" ], "x-extensible-enum": [ "pix_document", "bank_account" ], "title": "DisbursementMethod", "description": "Como o cedente e desembolsado na operacao. `pix_document`: PIX na chave do CPF/CNPJ do cedente — inclui o FALLBACK SILENCIOSO, em que dado bancario incompleto nao vira erro e cai no PIX por documento. `bank_account`: transferencia para a conta informada, so quando `code`, `agency` e `account` vieram os TRES.\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "LiquidationMethod": { "type": "string", "enum": [ "PIX_ONLY", "BOLETO_ONLY", "PIX_AND_BOLETO", "ESCROW" ], "x-extensible-enum": [ "PIX_ONLY", "BOLETO_ONLY", "PIX_AND_BOLETO", "ESCROW" ], "title": "LiquidationMethod", "description": "Metodo de liquidacao configurado para o originador (enum `liquidation_method`).\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "OriginatorKind": { "type": "string", "enum": [ "PARTNER", "SELF_SERVICE_ASSIGNOR", "INTERMEDIARY" ], "x-extensible-enum": [ "PARTNER", "SELF_SERVICE_ASSIGNOR", "INTERMEDIARY" ], "title": "OriginatorKind", "description": "Natureza do originador (enum `originator_kind`).\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback." }, "WebhookEventType": { "type": "string", "enum": [ "proposal.created", "proposal.simulated", "proposal.approved", "proposal.denied", "proposal.expired", "operation.created", "operation.pre_approved", "operation.approved", "operation.contract_sent", "operation.contract_signed", "operation.paid", "operation.denied", "operation.cancelled", "operation.credit_analyzed", "operation.returning_capital_received", "operation.fully_returned", "operation.overdue", "title.paid", "title.partially_paid", "title.overdue", "stock.item_registered", "stock.item_consumed" ], "x-extensible-enum": [ "proposal.created", "proposal.simulated", "proposal.approved", "proposal.denied", "proposal.expired", "operation.created", "operation.pre_approved", "operation.approved", "operation.contract_sent", "operation.contract_signed", "operation.paid", "operation.denied", "operation.cancelled", "operation.credit_analyzed", "operation.returning_capital_received", "operation.fully_returned", "operation.overdue", "title.paid", "title.partially_paid", "title.overdue", "stock.item_registered", "stock.item_consumed" ], "title": "WebhookEventType", "description": "Tipo de evento de webhook assinavel (enum `webhook_event_type`). Nem todos sao emitidos hoje — os RESERVADOS podem ser assinados, mas nenhuma entrega ocorre ate a emissao ser ligada. Emitidos hoje: `operation.created`, `operation.approved`, `operation.contract_signed`, `operation.paid`, `operation.denied`, `operation.cancelled`, `operation.overdue`, `title.paid`, `title.partially_paid`, `stock.item_registered`.\n\nLISTA ABERTA: novos valores podem ser acrescentados sem mudanca de versao maior (ver `reference/versioning.md`). Trate valor desconhecido como desconhecido — nunca como erro fatal — e evite `switch` exaustivo sem ramo de fallback.", "examples": [ "operation.created" ] }, "WebhookEventEnvelope": { "type": "object", "properties": { "event_type": { "$ref": "#/components/schemas/WebhookEventType" }, "event_id": { "type": "string", "format": "uuid", "description": "Identificador unico do evento, gerado uma vez na emissao e preservado em todas as re-entregas. Use-o para deduplicar." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Instante do fato, ISO-8601 UTC com `Z` (segundos inteiros)." }, "data": { "type": "object", "additionalProperties": true, "description": "Carga do evento — as chaves variam por `event_type`." } }, "required": [ "event_type", "event_id", "occurred_at", "data" ], "title": "WebhookEventEnvelope", "description": "Envelope de TODO evento de webhook. O corpo entregue e sempre este objeto — `event_id` e `occurred_at` acompanham cada entrega." }, "WebhookEventProposalCreated": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "proposal.created" } } } ], "title": "WebhookEventProposalCreated", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookEventProposalSimulated": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "proposal.simulated" } } } ], "title": "WebhookEventProposalSimulated", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookEventProposalApproved": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "proposal.approved" } } } ], "title": "WebhookEventProposalApproved", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookEventProposalDenied": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "proposal.denied" } } } ], "title": "WebhookEventProposalDenied", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookEventProposalExpired": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "proposal.expired" } } } ], "title": "WebhookEventProposalExpired", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookDataOperationCreated": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" }, "display_number": { "type": "string" }, "opr_net_present_liquid_value": { "type": "string", "description": "Valor liquido da operacao no momento da criacao — o total a ser transferido ao cedente. Valor em BRL, string decimal com 2 casas (ex.: `9183.33`). Nome CANONICO publico; equivale EXATAMENTE a `opr_liquid_value` (mesmo numero, mesma semantica). Presente em todo evento EMITIDO a partir da adocao do vocabulario publico; re-entregas de eventos gerados ANTES dela carregam apenas o nome deprecado, porque o espelho e aplicado na EMISSAO e nao e retroativo. Por isso a chave nao e declarada obrigatoria: trate a AUSENCIA dela caindo no nome deprecado." }, "lifecycle_status": { "$ref": "#/components/schemas/OperationLifecycleStatus" }, "opr_liquid_value": { "type": "string", "description": "[DEPRECATED — use `opr_net_present_liquid_value`] Valor liquido da operacao no momento da criacao — o total a ser transferido ao cedente. Valor em BRL, string decimal com 2 casas (ex.: `9183.33`). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "required": [ "display_number", "lifecycle_status", "operation_id", "opr_liquid_value" ], "additionalProperties": true, "title": "WebhookDataOperationCreated", "description": "Carga de `operation.created`." }, "WebhookEventOperationCreated": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.created" }, "data": { "$ref": "#/components/schemas/WebhookDataOperationCreated" } } } ], "title": "WebhookEventOperationCreated", "description": "Operacao criada. Quando precisa de aprovacao do Backoffice nasce em `WAITING_APPROVAL`; caso contrario em `APPROVED_DIRECT`." }, "WebhookEventOperationPreApproved": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.pre_approved" } } } ], "title": "WebhookEventOperationPreApproved", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookDataOperationApproved": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" }, "display_number": { "type": "string" }, "lifecycle_status": { "$ref": "#/components/schemas/OperationLifecycleStatus" }, "approved_at": { "type": "string", "format": "date-time" } }, "required": [ "approved_at", "display_number", "lifecycle_status", "operation_id" ], "additionalProperties": true, "title": "WebhookDataOperationApproved", "description": "Carga de `operation.approved`." }, "WebhookEventOperationApproved": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.approved" }, "data": { "$ref": "#/components/schemas/WebhookDataOperationApproved" } } } ], "title": "WebhookEventOperationApproved", "description": "Operacao aprovada (pelo Backoffice ou automaticamente, dentro do limite)." }, "WebhookEventOperationContractSent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.contract_sent" } } } ], "title": "WebhookEventOperationContractSent", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookDataOperationContractSigned": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "signed_at": { "type": "string", "format": "date-time" } }, "required": [ "contract_id", "operation_id", "signed_at" ], "additionalProperties": true, "title": "WebhookDataOperationContractSigned", "description": "Carga de `operation.contract_signed`." }, "WebhookEventOperationContractSigned": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.contract_signed" }, "data": { "$ref": "#/components/schemas/WebhookDataOperationContractSigned" } } } ], "title": "WebhookEventOperationContractSigned", "description": "Todos os signatarios assinaram o contrato." }, "WebhookDataOperationPaid": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" }, "display_number": { "type": "string" }, "opr_net_present_liquid_value": { "type": "string", "description": "Valor efetivamente transferido ao cedente neste PIX. Valor em BRL, string decimal com 2 casas (ex.: `9183.33`). Nome CANONICO publico; equivale EXATAMENTE a `opr_liquid_value` (mesmo numero, mesma semantica). Presente em todo evento EMITIDO a partir da adocao do vocabulario publico; re-entregas de eventos gerados ANTES dela carregam apenas o nome deprecado, porque o espelho e aplicado na EMISSAO e nao e retroativo. Por isso a chave nao e declarada obrigatoria: trate a AUSENCIA dela caindo no nome deprecado." }, "payment_sent_at": { "type": "string", "format": "date-time" }, "opr_liquid_value": { "type": "string", "description": "[DEPRECATED — use `opr_net_present_liquid_value`] Valor efetivamente transferido ao cedente neste PIX. Valor em BRL, string decimal com 2 casas (ex.: `9183.33`). Aceito em TODA a serie 1.x e REMOVIDO na versao 2.0 (nova versao de URL `/v2`), anunciada no Changelog como mudanca MAIOR. Hoje os dois nomes sao aceitos e devolvidos, com o mesmo valor; migre para o nome canonico." } }, "required": [ "display_number", "operation_id", "opr_liquid_value", "payment_sent_at" ], "additionalProperties": true, "title": "WebhookDataOperationPaid", "description": "Carga de `operation.paid`." }, "WebhookEventOperationPaid": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.paid" }, "data": { "$ref": "#/components/schemas/WebhookDataOperationPaid" } } } ], "title": "WebhookEventOperationPaid", "description": "PIX enviado ao cedente. `opr_net_present_liquid_value` (nome canonico de `opr_liquid_value`) e o valor efetivamente transferido." }, "WebhookDataOperationDenied": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "operation_id", "reason" ], "additionalProperties": true, "title": "WebhookDataOperationDenied", "description": "Carga de `operation.denied`." }, "WebhookEventOperationDenied": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.denied" }, "data": { "$ref": "#/components/schemas/WebhookDataOperationDenied" } } } ], "title": "WebhookEventOperationDenied", "description": "Operacao negada pelo Backoffice. `reason` pode vir `null`." }, "WebhookDataOperationCancelled": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" }, "cancelled_at": { "type": "string", "format": "date-time" } }, "required": [ "cancelled_at", "operation_id" ], "additionalProperties": true, "title": "WebhookDataOperationCancelled", "description": "Carga de `operation.cancelled`." }, "WebhookEventOperationCancelled": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.cancelled" }, "data": { "$ref": "#/components/schemas/WebhookDataOperationCancelled" } } } ], "title": "WebhookEventOperationCancelled", "description": "Operacao cancelada pelo originador." }, "WebhookEventOperationCreditAnalyzed": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.credit_analyzed" } } } ], "title": "WebhookEventOperationCreditAnalyzed", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookEventOperationReturningCapitalReceived": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.returning_capital_received" } } } ], "title": "WebhookEventOperationReturningCapitalReceived", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookEventOperationFullyReturned": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.fully_returned" } } } ], "title": "WebhookEventOperationFullyReturned", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookDataOperationOverdue": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" }, "overdue_titles_count": { "type": "integer" }, "total_outstanding_brl": { "type": "string", "description": "Valor em BRL, string decimal com 2 casas (ex.: `9183.33`)." } }, "required": [ "operation_id", "overdue_titles_count", "total_outstanding_brl" ], "additionalProperties": true, "title": "WebhookDataOperationOverdue", "description": "Carga de `operation.overdue`." }, "WebhookEventOperationOverdue": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "operation.overdue" }, "data": { "$ref": "#/components/schemas/WebhookDataOperationOverdue" } } } ], "title": "WebhookEventOperationOverdue", "description": "Um ou mais titulos da operacao venceram sem pagamento total." }, "WebhookDataTitlePaid": { "type": "object", "properties": { "title_id": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string", "format": "uuid" }, "face_value": { "type": "string", "description": "Valor em BRL, string decimal com 2 casas (ex.: `9183.33`)." }, "total_returned_value": { "type": "string", "description": "Valor em BRL, string decimal com 2 casas (ex.: `9183.33`)." }, "fully_returned_at": { "type": "string", "format": "date-time" } }, "required": [ "face_value", "fully_returned_at", "operation_id", "title_id", "total_returned_value" ], "additionalProperties": true, "title": "WebhookDataTitlePaid", "description": "Carga de `title.paid`." }, "WebhookEventTitlePaid": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "title.paid" }, "data": { "$ref": "#/components/schemas/WebhookDataTitlePaid" } } } ], "title": "WebhookEventTitlePaid", "description": "Titulo individual totalmente liquidado." }, "WebhookDataTitlePartiallyPaid": { "type": "object", "properties": { "title_id": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string", "format": "uuid" }, "payment_amount_brl": { "type": "string", "description": "Valor em BRL, string decimal com 2 casas (ex.: `9183.33`)." }, "outstanding_brl": { "type": "string", "description": "Valor em BRL, string decimal com 2 casas (ex.: `9183.33`)." } }, "required": [ "operation_id", "outstanding_brl", "payment_amount_brl", "title_id" ], "additionalProperties": true, "title": "WebhookDataTitlePartiallyPaid", "description": "Carga de `title.partially_paid`." }, "WebhookEventTitlePartiallyPaid": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "title.partially_paid" }, "data": { "$ref": "#/components/schemas/WebhookDataTitlePartiallyPaid" } } } ], "title": "WebhookEventTitlePartiallyPaid", "description": "Pagamento parcial recebido em um titulo." }, "WebhookEventTitleOverdue": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "title.overdue" } } } ], "title": "WebhookEventTitleOverdue", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookDataStockItemRegistered": { "type": "object", "properties": { "stock_item_id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "face_value": { "type": "string", "description": "Valor em BRL, string decimal com 2 casas (ex.: `9183.33`)." } }, "required": [ "external_id", "face_value", "stock_item_id" ], "additionalProperties": true, "title": "WebhookDataStockItemRegistered", "description": "Carga de `stock.item_registered`." }, "WebhookEventStockItemRegistered": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "stock.item_registered" }, "data": { "$ref": "#/components/schemas/WebhookDataStockItemRegistered" } } } ], "title": "WebhookEventStockItemRegistered", "description": "Recebivel registrado no estoque." }, "WebhookEventStockItemConsumed": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "event_type": { "const": "stock.item_consumed" } } } ], "title": "WebhookEventStockItemConsumed", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre." }, "WebhookEvent": { "oneOf": [ { "$ref": "#/components/schemas/WebhookEventProposalCreated" }, { "$ref": "#/components/schemas/WebhookEventProposalSimulated" }, { "$ref": "#/components/schemas/WebhookEventProposalApproved" }, { "$ref": "#/components/schemas/WebhookEventProposalDenied" }, { "$ref": "#/components/schemas/WebhookEventProposalExpired" }, { "$ref": "#/components/schemas/WebhookEventOperationCreated" }, { "$ref": "#/components/schemas/WebhookEventOperationPreApproved" }, { "$ref": "#/components/schemas/WebhookEventOperationApproved" }, { "$ref": "#/components/schemas/WebhookEventOperationContractSent" }, { "$ref": "#/components/schemas/WebhookEventOperationContractSigned" }, { "$ref": "#/components/schemas/WebhookEventOperationPaid" }, { "$ref": "#/components/schemas/WebhookEventOperationDenied" }, { "$ref": "#/components/schemas/WebhookEventOperationCancelled" }, { "$ref": "#/components/schemas/WebhookEventOperationCreditAnalyzed" }, { "$ref": "#/components/schemas/WebhookEventOperationReturningCapitalReceived" }, { "$ref": "#/components/schemas/WebhookEventOperationFullyReturned" }, { "$ref": "#/components/schemas/WebhookEventOperationOverdue" }, { "$ref": "#/components/schemas/WebhookEventTitlePaid" }, { "$ref": "#/components/schemas/WebhookEventTitlePartiallyPaid" }, { "$ref": "#/components/schemas/WebhookEventTitleOverdue" }, { "$ref": "#/components/schemas/WebhookEventStockItemRegistered" }, { "$ref": "#/components/schemas/WebhookEventStockItemConsumed" } ], "discriminator": { "propertyName": "event_type", "mapping": { "proposal.created": "#/components/schemas/WebhookEventProposalCreated", "proposal.simulated": "#/components/schemas/WebhookEventProposalSimulated", "proposal.approved": "#/components/schemas/WebhookEventProposalApproved", "proposal.denied": "#/components/schemas/WebhookEventProposalDenied", "proposal.expired": "#/components/schemas/WebhookEventProposalExpired", "operation.created": "#/components/schemas/WebhookEventOperationCreated", "operation.pre_approved": "#/components/schemas/WebhookEventOperationPreApproved", "operation.approved": "#/components/schemas/WebhookEventOperationApproved", "operation.contract_sent": "#/components/schemas/WebhookEventOperationContractSent", "operation.contract_signed": "#/components/schemas/WebhookEventOperationContractSigned", "operation.paid": "#/components/schemas/WebhookEventOperationPaid", "operation.denied": "#/components/schemas/WebhookEventOperationDenied", "operation.cancelled": "#/components/schemas/WebhookEventOperationCancelled", "operation.credit_analyzed": "#/components/schemas/WebhookEventOperationCreditAnalyzed", "operation.returning_capital_received": "#/components/schemas/WebhookEventOperationReturningCapitalReceived", "operation.fully_returned": "#/components/schemas/WebhookEventOperationFullyReturned", "operation.overdue": "#/components/schemas/WebhookEventOperationOverdue", "title.paid": "#/components/schemas/WebhookEventTitlePaid", "title.partially_paid": "#/components/schemas/WebhookEventTitlePartiallyPaid", "title.overdue": "#/components/schemas/WebhookEventTitleOverdue", "stock.item_registered": "#/components/schemas/WebhookEventStockItemRegistered", "stock.item_consumed": "#/components/schemas/WebhookEventStockItemConsumed" } }, "title": "WebhookEvent", "description": "Qualquer evento entregue no endpoint do integrador, discriminado por `event_type`. Use este schema para tipar UM receiver que trata todos os eventos; as entradas de `webhooks` descrevem cada evento isoladamente. Como `WebhookEventType` e LISTA ABERTA, mantenha um ramo de fallback para `event_type` desconhecido." } }, "headers": { "XRequestId": { "description": "Identificador desta requisicao. Ecoa o `X-Request-Id` recebido quando ele casa `^[A-Za-z0-9_-]{8,64}$`; caso contrario a API gera um UUID. Cite-o ao abrir suporte.", "schema": { "type": "string" }, "required": true }, "XCorrelationId": { "description": "Rastro ponta a ponta. Ecoa o `X-Correlation-Id` recebido (`^[A-Za-z0-9_.-]{8,128}$`); na ausencia herda o `X-Request-Id`.", "schema": { "type": "string" }, "required": true }, "XZemoEnv": { "description": "Ambiente que atendeu a requisicao (ex.: `sandbox`, `prod`).", "schema": { "type": "string" }, "required": true }, "XZemoAPIVersion": { "description": "Versao da API que atendeu a requisicao.", "schema": { "type": "string" }, "required": true }, "XRateLimitLimit": { "description": "Teto de requisicoes por minuto do bucket que avaliou esta requisicao. Ausente quando o rate limit esta degradado (fail-open).", "schema": { "type": "integer" } }, "XRateLimitRemaining": { "description": "Requisicoes restantes na janela de 1 minuto. Num 429 o valor e sempre `0` e vem do bucket que NEGOU.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Segundos a aguardar antes de re-tentar.", "schema": { "type": "integer" }, "required": true } }, "securitySchemes": { "ClientId": { "type": "apiKey", "in": "header", "name": "X-Client-Id" }, "ClientSecret": { "type": "apiKey", "in": "header", "name": "X-Client-Secret" }, "BearerJWT": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT obtido via POST /v1/auth/token com corpo JSON." } } }, "tags": [ { "name": "health", "description": "Health checks" }, { "name": "auth", "description": "Autenticação de API (Client Credentials) e sessão de usuário (JWT)" }, { "name": "stock", "description": "Estoque de recebíveis" }, { "name": "simulation", "description": "Simulação de antecipação" }, { "name": "products", "description": "Catálogo de produtos financeiros (product_id)" }, { "name": "operations", "description": "Operações de antecipação" }, { "name": "operations-direct", "description": "Criação direta de operação" }, { "name": "titles", "description": "Títulos e saldo devedor" }, { "name": "payers", "description": "Sacados" }, { "name": "assignors", "description": "Cedentes" }, { "name": "bank-accounts", "description": "Contas bancárias" }, { "name": "originators", "description": "Dados do originador" }, { "name": "assignor-payables", "description": "Payables pós-antecipação" }, { "name": "discount-credits", "description": "Créditos de desconto" }, { "name": "webhooks", "description": "Webhooks outbound" } ], "webhooks": { "proposal.created": { "post": { "tags": [ "webhooks" ], "summary": "Evento `proposal.created` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_proposal_created", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventProposalCreated" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "proposal.simulated": { "post": { "tags": [ "webhooks" ], "summary": "Evento `proposal.simulated` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_proposal_simulated", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventProposalSimulated" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "proposal.approved": { "post": { "tags": [ "webhooks" ], "summary": "Evento `proposal.approved` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_proposal_approved", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventProposalApproved" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "proposal.denied": { "post": { "tags": [ "webhooks" ], "summary": "Evento `proposal.denied` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_proposal_denied", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventProposalDenied" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "proposal.expired": { "post": { "tags": [ "webhooks" ], "summary": "Evento `proposal.expired` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_proposal_expired", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventProposalExpired" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.created": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.created`", "description": "Operacao criada. Quando precisa de aprovacao do Backoffice nasce em `WAITING_APPROVAL`; caso contrario em `APPROVED_DIRECT`.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_created", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationCreated" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.pre_approved": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.pre_approved` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_pre_approved", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationPreApproved" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.approved": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.approved`", "description": "Operacao aprovada (pelo Backoffice ou automaticamente, dentro do limite).\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_approved", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationApproved" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.contract_sent": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.contract_sent` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_contract_sent", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationContractSent" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.contract_signed": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.contract_signed`", "description": "Todos os signatarios assinaram o contrato.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_contract_signed", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationContractSigned" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.paid": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.paid`", "description": "PIX enviado ao cedente. `opr_net_present_liquid_value` (nome canonico de `opr_liquid_value`) e o valor efetivamente transferido.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_paid", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationPaid" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.denied": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.denied`", "description": "Operacao negada pelo Backoffice. `reason` pode vir `null`.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_denied", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationDenied" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.cancelled": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.cancelled`", "description": "Operacao cancelada pelo originador.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_cancelled", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationCancelled" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.credit_analyzed": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.credit_analyzed` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_credit_analyzed", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationCreditAnalyzed" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.returning_capital_received": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.returning_capital_received` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_returning_capital_received", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationReturningCapitalReceived" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.fully_returned": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.fully_returned` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_fully_returned", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationFullyReturned" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "operation.overdue": { "post": { "tags": [ "webhooks" ], "summary": "Evento `operation.overdue`", "description": "Um ou mais titulos da operacao venceram sem pagamento total.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_operation_overdue", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventOperationOverdue" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "title.paid": { "post": { "tags": [ "webhooks" ], "summary": "Evento `title.paid`", "description": "Titulo individual totalmente liquidado.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_title_paid", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventTitlePaid" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "title.partially_paid": { "post": { "tags": [ "webhooks" ], "summary": "Evento `title.partially_paid`", "description": "Pagamento parcial recebido em um titulo.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_title_partially_paid", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventTitlePartiallyPaid" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "title.overdue": { "post": { "tags": [ "webhooks" ], "summary": "Evento `title.overdue` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_title_overdue", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventTitleOverdue" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "stock.item_registered": { "post": { "tags": [ "webhooks" ], "summary": "Evento `stock.item_registered`", "description": "Recebivel registrado no estoque.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_stock_item_registered", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventStockItemRegistered" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } }, "stock.item_consumed": { "post": { "tags": [ "webhooks" ], "summary": "Evento `stock.item_consumed` (reservado, nao emitido)", "description": "RESERVADO no enum: pode ser assinado em `POST /v1/webhooks`, mas a API ainda NAO emite este evento — nenhuma entrega ocorre.\n\nA Zemo faz `POST` neste corpo para a URL HTTPS cadastrada. Responda `2xx` para confirmar; qualquer outro status, ou um timeout de 10s, conta como falha e agenda re-tentativa com backoff exponencial. Sao no MAXIMO 7 tentativas, com 6 esperas entre elas — 1, 2, 4, 8, 16 e 32 min — ou seja a ultima tentativa ocorre ~63 min depois da primeira. Ha ainda um prazo de desistencia (`give_up_at`) de ~128 min contado da primeira falha, que encerra as re-tentativas mesmo que sobrem ciclos. A entrega e at-least-once: deduplique por `event_id`.", "operationId": "webhook_stock_item_consumed", "parameters": [ { "name": "X-Zemo-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo BRUTO, em hex, com o `hmac_secret` do endpoint (devolvido uma unica vez no cadastro). Assine os bytes recebidos sem re-serializar o JSON.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Type", "in": "header", "required": true, "description": "Tipo do evento — o mesmo de `event_type` no corpo.", "schema": { "type": "string" } }, { "name": "X-Zemo-Event-Id", "in": "header", "required": true, "description": "UUID do evento — o mesmo de `event_id` no corpo. Chave de deduplicacao: a entrega e at-least-once e o MESMO `event_id` pode chegar mais de uma vez.", "schema": { "type": "string" } }, { "name": "X-Zemo-Timestamp", "in": "header", "required": true, "description": "Instante do envio, ISO-8601 UTC.", "schema": { "type": "string" } }, { "name": "X-Zemo-Signature-V2", "in": "header", "required": false, "description": "Assinatura versionada (`v1=` com o carimbo de tempo ligado ao material assinado). Presente apenas onde a v2 esta habilitada; a v1 acima e sempre enviada.", "schema": { "type": "string" } }, { "name": "X-Zemo-Retry-Attempt", "in": "header", "required": false, "description": "Numero da re-tentativa desta entrega. Ausente na primeira tentativa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventStockItemConsumed" } } } }, "responses": { "2XX": { "description": "Evento aceito. Qualquer 2xx encerra a entrega; o corpo da resposta e ignorado." } } } } }, "servers": [ { "url": "https://receivables-api-sandbox.zemocapital.com", "description": "Sandbox (homologacao)" }, { "url": "https://receivables-api.zemocapital.com", "description": "Producao" } ], "security": [ { "ClientId": [], "ClientSecret": [] }, { "BearerJWT": [] } ] }