{ "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.1.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" } } }, "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: `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": "Recurso bloqueado. Conta bloqueada temporariamente. `detail` e uma string.\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" } } }, "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 M2M.\n// Para M2M use as credenciais no construtor (acima). Se precisar mesmo:\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": "Exchange M2M credentials for JWT", "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" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/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 M2M invalido\n\nCodigos possiveis nesta operacao: `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" } } }, "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" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockItemCreateResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/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`.\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" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/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 M2M (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_face_value=10000.00,\n net_face_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`.\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" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockSimulationResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/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`, `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`.\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`, `LIMIT_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 M2M (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 requested_advance_value=10000.00,\n fees=zemo.Fees(monthly_rate_pct=3.5),\n)\nprint(sim.opr_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" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationCreateResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/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`, `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`.\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`, `LIMIT_MAX_OPERATION_VALUE`, `LIMIT_MIN_TERM_DAYS`, `LIMIT_MAX_TERM_DAYS`, `LIMIT_CONFIG_MISSING`, `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 M2M (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_advance_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" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/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`.\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\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 M2M (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_face_value=10000.00,\n requested_advance_value=10000.00,\n due_date=\"2026-08-15\",\n )],\n fees=zemo.Fees(monthly_rate_pct=3.5),\n)\nprint(sim.opr_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.", "operationId": "create_operation_direct_v1_operations_direct_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectOperationCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationCreateResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/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`, `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`.\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`, `LIMIT_MAX_OPERATION_VALUE`, `LIMIT_MIN_TERM_DAYS`, `LIMIT_MAX_TERM_DAYS`, `LIMIT_CONFIG_MISSING`, `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 M2M (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_face_value=10000.00,\n requested_advance_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/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" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/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" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-Correlation-Id": { "$ref": "#/components/headers/XCorrelationId" }, "X-Zemo-Env": { "$ref": "#/components/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 do banco (3 digitos). Obrigatorio para conta bancaria.", "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" }, "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)." }, "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" }, { "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.", "examples": [ 3.5 ] }, "discount_pct": { "anyOf": [ { "type": "number" }, { "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.", "examples": [ 2.0 ] }, "fixed_discount_brl": { "anyOf": [ { "type": "number" }, { "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.", "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 SEMPRE 'WAITING_APPROVAL' (o fluxo direto nao tem auto-aprovacao). 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_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Face 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` no fluxo direto e `gross_face_value` no fluxo de estoque. Nao e o valor pago ao cedente." }, "opr_net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Net Face 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)." }, "opr_discounted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Discounted Value", "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`)." }, "opr_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr 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." }, "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" }, "needs_backoffice_approval": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Needs Backoffice Approval" }, "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" } }, "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_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Face 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` no fluxo direto e `gross_face_value` no fluxo de estoque. Nao e o valor pago ao cedente." }, "opr_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr 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." }, "opr_discounted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Discounted Value", "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`)." }, "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" } }, "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_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Gross Face 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` no fluxo direto e `gross_face_value` no fluxo de estoque. Nao e o valor pago ao cedente." }, "opr_liquid_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr 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." }, "opr_discounted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opr Discounted Value", "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`)." }, "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" } }, "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.", "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).", "examples": [ "REC-001" ] }, "payer_name": { "type": "string", "title": "Payer Name", "description": "Nome ou razao social do sacado (devedor do recebivel)", "examples": [ "Empresa XYZ Ltda" ] }, "payer_document": { "type": "string", "title": "Payer Document", "description": "CPF (11 digitos) ou CNPJ (14 digitos) do sacado", "examples": [ "98765432000198" ] }, "gross_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Gross Face 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 de net_face_value.", "examples": [ 12000.0 ] }, "net_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" } ], "title": "Net Face Value", "description": "Net Face Value (NFV) 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: requested_advance_value nao pode exceder este valor.", "examples": [ 10000.0 ] }, "requested_advance_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" } ], "title": "Requested Advance Value", "description": "Quanto do Net Face Value esta sendo antecipado deste recebivel (BRL, valor ABSOLUTO — nao existe campo de percentual; o percentual e requested_advance_value / net_face_value). Deve ser <= net_face_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. ATENCAO ao `pre_authorized`: ele e HERDADO do item de origem no estoque e, quando o recebivel nao veio do estoque (o caso comum desta rota), nasce `false` (fail-closed) — nesse estado a antecipacao do resto e recusada com 409 `stock_item__not_pre_authorized`. Libere antes com `PATCH /v1/stock/{item_id}` (`pre_authorized: true`).", "examples": [ 10000.0 ] }, "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.", "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...).", "examples": [ "NFE" ] }, "monthly_rate_pct": { "anyOf": [ { "type": "number" }, { "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).", "examples": [ 3.5 ] }, "discount_pct": { "anyOf": [ { "type": "number" }, { "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.", "examples": [ 2.0 ] }, "fixed_discount_brl": { "anyOf": [ { "type": "number" }, { "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.", "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. O CET resultante sera validado contra os limites da policy do originador.", "examples": [ 9500.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_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": "Obrigatorio e VALIDADO: deve ser EXATAMENTE igual a soma do `net_face_value` (Net Face 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`. Para fixar o liquido a receber use `fees.total_liquid_value_brl`." }, "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" ] } }, "type": "object", "required": [ "stock_item_ids", "requested_advance_value", "bank" ], "title": "RequestAnticipationFromStock" }, "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_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": "Obrigatorio e VALIDADO com o MESMO criterio do `request-anticipation` (veredito simulado = veredito do request): deve ser EXATAMENTE igual a soma do `net_face_value` (NFV, Net Face 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`." }, "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" ] } }, "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" }, "requested_advance_value": { "type": "string", "title": "Requested Advance Value" }, "net_face_value": { "type": "string", "title": "Net Face Value" }, "gross_face_value": { "type": "string", "title": "Gross Face Value" }, "due_date": { "type": "string", "title": "Due Date" }, "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" }, "discounted_value": { "type": "string", "title": "Discounted Value", "description": "Desconto total cumulativo (R$)" }, "liquid_value": { "type": "string", "title": "Liquid Value", "description": "Valor liquido do recebivel (R$)" }, "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" } }, "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" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Monthly Rate Pct", "description": "Taxa mensal (%), pro-rata dias. Cumulativa.", "examples": [ 3.5 ] }, "discount_pct": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Discount Pct", "description": "Desagio fixo (%) sobre valor. Cumulativa.", "examples": [ 2.0 ] }, "fixed_discount_brl": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Fixed Discount Brl", "description": "Desconto nominal fixo em reais por recebivel. Cumulativo.", "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" ] }, "gross_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Gross Face Value", "description": "Valor de face BRUTO do lastro (NF antes dos descontos aplicados a ela). Opcional.", "examples": [ 12000.0 ] }, "net_face_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" } ], "title": "Net Face Value", "description": "Net Face Value (NFV) do recebivel — valor de face FUTURO, LIQUIDO dos descontos ja aplicados ao lastro (impostos na fonte ou outros). Teto da antecipacao.", "examples": [ 10000.0 ] }, "requested_advance_value": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" } ], "title": "Requested Advance Value", "description": "Quanto do Net Face Value se antecipa (BRL, valor ABSOLUTO — nao ha campo de percentual). Se < net_face_value, antecipacao PARCIAL. A simulacao nao cria o item-resto: o remainder no estoque nasce em `POST /v1/operations/direct`.", "examples": [ 10000.0 ] }, "due_date": { "type": "string", "title": "Due Date", "description": "Data de vencimento do recebivel (YYYY-MM-DD)", "examples": [ "2026-08-15" ] }, "monthly_rate_pct": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Monthly Rate Pct", "description": "Taxa mensal (%), pro-rata dias. Cumulativa.", "examples": [ 3.5 ] }, "discount_pct": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Discount Pct", "description": "Desagio fixo (%) sobre valor, independente do prazo.", "examples": [ 2.0 ] }, "fixed_discount_brl": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Fixed Discount Brl", "description": "Desconto nominal fixo em reais.", "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 ] } }, "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_face_value": { "type": "string", "title": "Opr Gross Face 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` no fluxo direto e `gross_face_value` no fluxo de estoque. Nao e o valor pago ao cedente." }, "opr_net_face_value": { "type": "string", "title": "Opr Net Face 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)." }, "opr_discounted_value": { "type": "string", "title": "Opr Discounted Value" }, "opr_liquid_value": { "type": "string", "title": "Opr Liquid Value" }, "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" } }, "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" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Monthly Rate Pct", "description": "Taxa mensal (%), pro-rata dias. Cumulativa." }, "discount_pct": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Discount Pct", "description": "Desagio fixo (%) sobre valor." }, "fixed_discount_brl": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Fixed Discount Brl", "description": "Desconto nominal fixo em reais." }, "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" }, "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": "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_face_value` (NFV). E a grandeza dos LIMITES agregados de exposicao e do cap de valor do token, e o teto do proprio NFV (`net_face_value` maior que este valor => 422)." }, "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": "Net Face Value (NFV) 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_face_value`, o que o saldo do estoque soma e a BASE DO DESAGIO do fluxo de estoque. A diferenca `gross_face_value - net_face_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`." }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "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" } }, "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" }, "gross_face_value": { "type": "string", "title": "Gross Face Value" }, "net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Face Value" }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "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" } }, "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" }, "gross_face_value": { "type": "string", "title": "Gross Face Value" }, "net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Face Value" }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "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" } }, "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" }, "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": "Valor de face BRUTO do lastro (antes dos descontos aplicados a ele)." }, "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": "Net Face Value (NFV) do lastro — valor de face futuro, LIQUIDO dos descontos ja aplicados a ele. Alimenta `opr_net_face_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)." }, "due_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Due Date" }, "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" } }, "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" }, "gross_face_value": { "type": "string", "title": "Gross Face Value", "description": "Valor de face BRUTO do item de estoque. NAO e a base do desagio: a base deste fluxo e o `net_face_value` (NFV). A diferenca entre os dois e informacao gerencial (descontos ja aplicados ao lastro)." }, "net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Face Value", "description": "Net Face Value (NFV) do item — valor de face futuro LIQUIDO dos descontos aplicados ao lastro. E o valor-base do desagio deste recebivel no fluxo de estoque." }, "requested_advance_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Requested Advance Value", "description": "Valor solicitado no cadastro do item. ECO do estoque — a simulacao a partir do estoque calcula o desagio sobre `net_face_value`, nao sobre este campo. O fluxo de estoque antecipa sempre 100% do item selecionado; antecipacao PARCIAL so existe em `POST /v1/operations/direct`." }, "due_date": { "type": "string", "title": "Due Date" }, "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." }, "discount_brl": { "type": "string", "title": "Discount Brl", "description": "Desagio cobrado neste recebivel, em BRL." }, "liquid_value": { "type": "string", "title": "Liquid Value", "description": "Valor liquido deste recebivel = `net_face_value` (a base do desagio no fluxo de estoque) menos `discount_brl`." }, "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" } }, "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_face_value": { "type": "string", "title": "Opr Gross Face 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` no fluxo direto e `gross_face_value` no fluxo de estoque. Nao e o valor pago ao cedente." }, "opr_net_face_value": { "type": "string", "title": "Opr Net Face 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)." }, "opr_discounted_value": { "type": "string", "title": "Opr Discounted Value", "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`)." }, "opr_liquid_value": { "type": "string", "title": "Opr 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." }, "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" } }, "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" }, "gross_face_value": { "type": "string", "title": "Gross Face Value", "description": "Valor de face BRUTO do recebivel (valor nominal da NF-e/duplicata, antes de deducoes)." }, "liquid_value": { "type": "string", "title": "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. ATENCAO — a base depende da porta que criou a operacao: no fluxo DIRETO e o `requested_advance_value` do titulo (entao `requested_advance_value - discounted_value` fecha); no fluxo de ESTOQUE e o `net_face_value`, enquanto o titulo grava o `gross_face_value` do item em `requested_advance_value` — com descontos de lastro os dois DIFEREM e a subtracao pelo `requested_advance_value` NAO fecha. Ver `net_face_value` em `GET /v1/titles/{id}`." }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "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" }, "net_face_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Face Value", "description": "Net Face Value (NFV) 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). ATENCAO no estoque: o titulo nasce com `requested_advance_value` igual ao `gross_face_value` do item (convencao pre-existente do fluxo), entao o liquido do titulo e `net_face_value - discounted_value` e NAO `requested_advance_value - discounted_value`." }, "discounted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Discounted Value", "description": "Desagio cobrado neste titulo (taxa mensal pro-rata sobre os dias cobrados + desagio percentual + desconto fixo)." }, "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" } }, "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" }, "gross_face_value": { "type": "string", "title": "Gross Face Value", "description": "Valor de face BRUTO do recebivel (valor nominal da NF-e/duplicata, antes de deducoes)." }, "liquid_value": { "type": "string", "title": "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. ATENCAO — a base depende da porta que criou a operacao: no fluxo DIRETO e o `requested_advance_value` do titulo (entao `requested_advance_value - discounted_value` fecha); no fluxo de ESTOQUE e o `net_face_value`, enquanto o titulo grava o `gross_face_value` do item em `requested_advance_value` — com descontos de lastro os dois DIFEREM e a subtracao pelo `requested_advance_value` NAO fecha. Ver `net_face_value` em `GET /v1/titles/{id}`." }, "due_date": { "type": "string", "format": "date", "title": "Due Date" }, "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" } }, "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": "M2M credential X-Client-Id" }, "client_secret": { "type": "string", "minLength": 8, "title": "Client Secret", "description": "M2M credential 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." }, "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_liquid_value": { "type": "string", "description": "Valor em BRL, string decimal com 2 casas (ex.: `9183.33`)." }, "lifecycle_status": { "$ref": "#/components/schemas/OperationLifecycleStatus" } }, "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_liquid_value": { "type": "string", "description": "Valor em BRL, string decimal com 2 casas (ex.: `9183.33`)." }, "payment_sent_at": { "type": "string", "format": "date-time" } }, "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_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 JWT e M2M" }, { "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_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": [] } ] }