{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Convenções da API","description":"Documentação oficial da API da plataforma de crédito embarcado Dinie. Integre produtos de crédito diretamente na sua aplicação.","siteUrl":"https://docs.dinie.com","lang":"pt-BR","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"convenções-da-api","__idx":0},"children":["Convenções da API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Esta página documenta as convenções de design que se aplicam a todos os endpoints da API Dinie. Entender essas convenções ajuda você a prever o comportamento da API mesmo antes de consultar a referência de cada endpoint."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"versionamento","__idx":1},"children":["Versionamento"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A versão principal está no path da URL: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/..."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Todas as respostas incluem o header de versão:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"X-API-Version: 2026-03-01\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A versão usa o formato de data (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]},"). Mudanças não-quebra (novos campos, novos endpoints, novos eventos de webhook) são introduzidas sob uma nova data. Mudanças que quebram compatibilidade exigem uma nova versão principal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"urls-e-recursos","__idx":2},"children":["URLs e Recursos"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"formato-dos-paths","__idx":3},"children":["Formato dos Paths"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Segmentos de URL usam ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["kebab-case"]},", em letras minúsculas:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"/v3/credit-offers/{id}\n/v3/credit-offers/{id}/simulations\n/v3/webhooks/endpoints/{id}/secret/rotate\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"nomes-de-recursos","__idx":4},"children":["Nomes de Recursos"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Substantivos no plural para coleções: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/customers"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/credit-offers"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/loans"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Recurso individual acessado via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/{coleção}/{id}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sub-recursos aninhados sob o recurso pai: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/customers/{id}/kyc-attachments"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Aninhamento vai no máximo 2 níveis de profundidade"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ações","__idx":5},"children":["Ações"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ações que não são CRUD usam um sufixo de verbo no path:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /v3/webhooks/endpoints/{id}/secret/rotate\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"nomes-de-campos","__idx":6},"children":["Nomes de Campos"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"corpos-de-requisição-e-resposta","__idx":7},"children":["Corpos de Requisição e Resposta"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Todos os nomes de campos usam ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["snake_case"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"approved_amount\": 50000.00,\n  \"interest_rate\": 3.50,\n  \"created_at\": 1709546400\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sem camelCase, PascalCase ou kebab-case em corpos JSON."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parâmetros-de-query","__idx":8},"children":["Parâmetros de Query"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Parâmetros de query também usam ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["snake_case"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /v3/customers?external_id=partner123&starting_after=cust_abc123\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"headers","__idx":9},"children":["Headers"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Headers de webhook: minúsculas com hifens (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-timestamp"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-signature"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Headers OAuth: padrão (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer ..."]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Headers da API: prefixo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-"]}," com segmentos PascalCase (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-API-Version"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-Limit"]},")"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"data-e-hora","__idx":10},"children":["Data e Hora"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"timestamps","__idx":11},"children":["Timestamps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Todos os campos de data/hora usam ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Unix epoch"]}," (inteiro, segundos desde 1 de janeiro de 1970 UTC):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"created_at\": 1709546400\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No OpenAPI: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: integer, format: int64"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nenhum fuso horário é incluído no valor -- timestamps Unix são inerentemente UTC."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"campos-somente-data","__idx":12},"children":["Campos Somente Data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Campos que representam uma data de calendário sem componente de hora usam ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ISO 8601 date"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]},") como string:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"due_date\": \"2026-04-03\"\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No OpenAPI: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: string, format: date"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"valores-monetários","__idx":13},"children":["Valores Monetários"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Todos os valores monetários são representados como ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["números JSON"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]},") com precisão de duas casas decimais:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"approved_amount\": 50000.00,\n  \"monthly_payment\": 2289.42,\n  \"iof\": 450.00\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"regras","__idx":14},"children":["Regras"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Moeda é sempre BRL (Real Brasileiro) — não incluída na resposta, pois a plataforma opera exclusivamente em BRL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Precisão: sempre exatamente 2 casas decimais"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Formato no OpenAPI: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: number, format: double"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"campos-nulos","__idx":15},"children":["Campos Nulos"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Campos sem valor são incluídos na resposta como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," em vez de omitidos. Isso torna o schema da resposta previsível independente do estado:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"cust_abc123\",\n  \"trading_name\": null,\n  \"expires_at\": null,\n  \"approved_amount\": null\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No OpenAPI, campos nullable usam ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: [\"string\", \"null\"]"]}," (sintaxe JSON Schema 2020-12, suportada no OpenAPI 3.1)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"campos-desconhecidos","__idx":16},"children":["Campos Desconhecidos"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Campos desconhecidos em corpos de requisição são ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["silenciosamente ignorados"]}," (não rejeitados). Isso permite compatibilidade futura quando novos campos são adicionados. A especificação OpenAPI ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["não"]}," define ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["additionalProperties: false"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Da mesma forma, ao receber respostas da API, seu código deve ignorar campos que não reconhece — novos campos podem ser adicionados sem aviso prévio em versões menores."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"campos-comuns-de-resposta","__idx":17},"children":["Campos Comuns de Resposta"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Estes campos aparecem na maioria dos recursos:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Campo"},"children":["Campo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tipo"},"children":["Tipo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Formato"},"children":["Formato"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Descrição"},"children":["Descrição"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ID prefixado"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identificador único do recurso (ex.: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cust_"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ln_"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["co_"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["enum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Estado atual do ciclo de vida (quando aplicável)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int64"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unix epoch (segundos) de criação"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updated_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int64"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unix epoch (segundos) da última modificação (quando aplicável)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"identificadores","__idx":18},"children":["Identificadores"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Todos os IDs expostos pela API são ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["prefixo + UUID sem hifens"]},". O prefixo indica o tipo de recurso:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Recurso"},"children":["Recurso"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Prefixo"},"children":["Prefixo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Exemplo"},"children":["Exemplo"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cliente"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cust_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cust_550e8400e29b41d4a716446655440000"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Oferta de Crédito"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["co_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["co_550e8400e29b41d4a716446655440000"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Empréstimo"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ln_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ln_550e8400e29b41d4a716446655440000"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Simulação"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sim_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sim_550e8400e29b41d4a716446655440000"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transação"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tx_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tx_550e8400e29b41d4a716446655440000"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Endpoint de Webhook"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["we_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["we_550e8400e29b41d4a716446655440000"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["IDs são sempre strings, nunca inteiros. São imutáveis durante toda a vida do recurso."]}]},"headings":[{"value":"Convenções da API","id":"convenções-da-api","depth":1},{"value":"Versionamento","id":"versionamento","depth":2},{"value":"URLs e Recursos","id":"urls-e-recursos","depth":2},{"value":"Formato dos Paths","id":"formato-dos-paths","depth":3},{"value":"Nomes de Recursos","id":"nomes-de-recursos","depth":3},{"value":"Ações","id":"ações","depth":3},{"value":"Nomes de Campos","id":"nomes-de-campos","depth":2},{"value":"Corpos de Requisição e Resposta","id":"corpos-de-requisição-e-resposta","depth":3},{"value":"Parâmetros de Query","id":"parâmetros-de-query","depth":3},{"value":"Headers","id":"headers","depth":3},{"value":"Data e Hora","id":"data-e-hora","depth":2},{"value":"Timestamps","id":"timestamps","depth":3},{"value":"Campos Somente Data","id":"campos-somente-data","depth":3},{"value":"Valores Monetários","id":"valores-monetários","depth":2},{"value":"Regras","id":"regras","depth":3},{"value":"Campos Nulos","id":"campos-nulos","depth":2},{"value":"Campos Desconhecidos","id":"campos-desconhecidos","depth":2},{"value":"Campos Comuns de Resposta","id":"campos-comuns-de-resposta","depth":2},{"value":"Identificadores","id":"identificadores","depth":3}],"frontmatter":{"seo":{"title":"Convenções da API"}},"lastModified":"2026-03-12T14:30:00.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/concepts/conventions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}