{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/en-US/apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"API Conventions","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":"api-conventions","__idx":0},"children":["API Conventions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page documents the design conventions that apply to all Dinie API endpoints. Understanding these conventions helps you predict API behavior even before consulting each endpoint's reference."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"versioning","__idx":1},"children":["Versioning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The major version is in the URL path: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/..."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All responses include the version header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"X-API-Version: 2026-03-01\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The version uses a date format (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]},"). Non-breaking changes (new fields, new endpoints, new webhook events) are introduced under a new date. Breaking changes require a new major version."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"urls-and-resources","__idx":2},"children":["URLs and Resources"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"path-format","__idx":3},"children":["Path Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["URL path segments use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["kebab-case"]},", lowercase:"]},{"$$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":"resource-naming","__idx":4},"children":["Resource Naming"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Plural nouns for collections: ",{"$$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":["Individual resource accessed via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/{collection}/{id}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sub-resources nested under parent: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/customers/{id}/kyc-attachments"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Nesting goes at most 2 levels deep"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"actions","__idx":5},"children":["Actions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Non-CRUD actions use a verb suffix on the resource 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":"field-naming","__idx":6},"children":["Field Naming"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-and-response-bodies","__idx":7},"children":["Request and Response Bodies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All field names use ",{"$$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":["No camelCase, PascalCase, or kebab-case in JSON bodies."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"query-parameters","__idx":8},"children":["Query Parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Query parameters also use ",{"$$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":["Webhook headers: lowercase with dashes (",{"$$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":["OAuth headers: standard (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer ..."]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["API headers: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-"]}," prefix with PascalCase segments (",{"$$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":"date-and-time","__idx":10},"children":["Date and Time"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"timestamps","__idx":11},"children":["Timestamps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All datetime fields use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Unix epoch"]}," (integer, seconds since January 1, 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":["In OpenAPI: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: integer, format: int64"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No timezone is included in the value -- Unix timestamps are inherently UTC."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"date-only-fields","__idx":12},"children":["Date-Only Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fields that represent a calendar date without a time component use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ISO 8601 date"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]},") as a 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":["In OpenAPI: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: string, format: date"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"monetary-values","__idx":13},"children":["Monetary Values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All monetary values are represented as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JSON numbers"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]},") with two decimal places of precision:"]},{"$$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":"rules","__idx":14},"children":["Rules"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Currency is always BRL (Brazilian Real) -- not included in the response since the platform operates exclusively in BRL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Precision: always exactly 2 decimal places"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["OpenAPI format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: number, format: double"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"null-fields","__idx":15},"children":["Null Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fields with no value are included in the response as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," rather than omitted. This makes the response schema predictable regardless of state:"]},{"$$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":["In OpenAPI, nullable fields use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: [\"string\", \"null\"]"]}," (JSON Schema 2020-12 syntax, supported in OpenAPI 3.1)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"unknown-fields","__idx":16},"children":["Unknown Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unknown fields in request bodies are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["silently ignored"]}," (not rejected). This allows forward compatibility when new fields are added. The OpenAPI specification does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["additionalProperties: false"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Similarly, when receiving API responses, your code should ignore fields it does not recognize -- new fields may be added without notice in minor versions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-response-fields","__idx":17},"children":["Common Response Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These fields appear on most resources:"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Format"},"children":["Format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$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":["Prefixed ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique resource identifier (e.g., ",{"$$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":["Current lifecycle state (when applicable)"]}]},{"$$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 (seconds) of creation"]}]},{"$$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 (seconds) of last modification (when applicable)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"identifiers","__idx":18},"children":["Identifiers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All IDs exposed by the API are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["prefix + UUID without dashes"]},". The prefix indicates the resource type:"]},{"$$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":"Resource"},"children":["Resource"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Prefix"},"children":["Prefix"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer"]},{"$$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":["Credit Offer"]},{"$$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":["Loan"]},{"$$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":["Simulation"]},{"$$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":["Transaction"]},{"$$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":["Webhook Endpoint"]},{"$$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 are always strings, never integers. They are immutable for the lifetime of the resource."]}]},"headings":[{"value":"API Conventions","id":"api-conventions","depth":1},{"value":"Versioning","id":"versioning","depth":2},{"value":"URLs and Resources","id":"urls-and-resources","depth":2},{"value":"Path Format","id":"path-format","depth":3},{"value":"Resource Naming","id":"resource-naming","depth":3},{"value":"Actions","id":"actions","depth":3},{"value":"Field Naming","id":"field-naming","depth":2},{"value":"Request and Response Bodies","id":"request-and-response-bodies","depth":3},{"value":"Query Parameters","id":"query-parameters","depth":3},{"value":"Headers","id":"headers","depth":3},{"value":"Date and Time","id":"date-and-time","depth":2},{"value":"Timestamps","id":"timestamps","depth":3},{"value":"Date-Only Fields","id":"date-only-fields","depth":3},{"value":"Monetary Values","id":"monetary-values","depth":2},{"value":"Rules","id":"rules","depth":3},{"value":"Null Fields","id":"null-fields","depth":2},{"value":"Unknown Fields","id":"unknown-fields","depth":2},{"value":"Common Response Fields","id":"common-response-fields","depth":2},{"value":"Identifiers","id":"identifiers","depth":3}],"frontmatter":{"seo":{"title":"API Conventions"}},"lastModified":"2026-03-19T21:33:27.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/en-us/apis/concepts/conventions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}