{ "openapi": "3.0.0", "info": { "title": "API de Integração Envio Fácil Encomendas", "version": "1.0", "description": "Contrato público enxuto para autenticação, endereços de remetentes e destinatários, cotação, criação de envios, emissão e download de etiquetas, DACE e rastreamento." }, "servers": [ { "url": "https://api.enviofacilencomendas.com.br", "description": "Produção" } ], "externalDocs": { "description": "Guia completo de integração", "url": "https://ajuda.enviofacilencomendas.com.br/api" }, "tags": [ { "name": "Autenticação", "description": "Criação e renovação da sessão da integração." }, { "name": "Endereços", "description": "Cadastro e consulta de remetentes e destinatários da loja." }, { "name": "Cotações", "description": "Simulações nacionais e internacionais da loja." }, { "name": "Envios", "description": "Criação do envio a partir de uma cotação válida." }, { "name": "Etiquetas", "description": "Emissão e download de etiquetas." }, { "name": "DACE", "description": "Geração, consulta e download de DACE." }, { "name": "Rastreamento", "description": "Consulta autenticada dos eventos da loja." } ], "paths": { "/api/v1/auth/login": { "post": { "operationId": "IdentityAccessAuthController_loginRoute", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginDto" } } } }, "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginSessionResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Autenticação" ], "summary": "Autenticar a integração", "description": "Troca o e-mail e a senha de uma conta ativa da Envio Fácil por tokens e pela lista de lojas autorizadas.", "security": [] } }, "/api/v1/auth/refresh": { "post": { "operationId": "IdentityAccessAuthController_refreshTokenRoute", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenDto" } } } }, "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshSessionResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Autenticação" ], "summary": "Renovar a sessão", "description": "Rotaciona o refresh token. Armazene os novos tokens e descarte o anterior.", "security": [] } }, "/api/v1/addresses": { "get": { "operationId": "AddressManagementBcController_list", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": false, "description": "Busca por nome ou dados do remetente.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressManagementListResponseDto" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Endereços" ], "summary": "Listar remetentes", "description": "Retorna os remetentes salvos na loja para consulta e reutilização." }, "post": { "operationId": "AddressManagementBcController_create", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressManagementBodyDto" } } } }, "responses": { "201": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressManagementResponseDto" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Endereços" ], "summary": "Cadastrar remetente", "description": "Salva os dados de identificação e endereço de um remetente da loja." } }, "/api/v1/recipients": { "get": { "operationId": "ShipmentBcRecipientsController_list", "parameters": [ { "name": "q", "required": false, "in": "query", "description": "Busca por nome, documento ou contato.", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientListResponseDto" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Endereços" ], "summary": "Listar destinatários", "description": "Retorna os destinatários salvos na loja, incluindo seus endereços." }, "post": { "operationId": "ShipmentBcRecipientsController_create", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientCreateDto" } } } }, "responses": { "201": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientResponseDto" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Endereços" ], "summary": "Cadastrar destinatário", "description": "Salva o destinatário e o endereço em que a encomenda será entregue." } }, "/api/v1/quotes/simulate": { "post": { "operationId": "ShipmentBcQuoteSimulationController_simulate", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreightSimulateDto" } } } }, "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteSimulationResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Cotações" ], "summary": "Simular frete nacional", "description": "Retorna as opções nacionais habilitadas para a loja.", "security": [ { "bearer": [] } ] } }, "/api/v1/quotes/simulate-international": { "post": { "operationId": "ShipmentBcQuoteSimulationController_simulateInternational", "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreightSimulateInternationalDto" } } } }, "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteSimulationResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Cotações" ], "summary": "Simular frete internacional", "description": "Retorna as opções internacionais habilitadas para a loja e para a rota.", "security": [ { "bearer": [] } ] } }, "/api/v1/shipments": { "post": { "operationId": "ShipmentBcController_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCreateShipmentDto" } } } }, "responses": { "201": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCreateShipmentResponseDto" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Envios" ], "summary": "Criar envio", "description": "Cria o envio com a opção selecionada na cotação. O servidor valida quoteId, loja, transportadora, serviço, rota, pacote e preço antes de retornar shipmentId.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/labels/shipments/{shipmentId}/emit": { "post": { "operationId": "ShipmentBcLabelsController_emit", "parameters": [ { "name": "shipmentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitLabelDto" } } } }, "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitLabelReadyResponse" } } } }, "202": { "description": "Emissão em processamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingLabelResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Etiquetas" ], "summary": "Emitir etiqueta", "description": "Compra e emite a etiqueta. Pode responder 202 durante processamento assíncrono.", "security": [ { "bearer": [] } ] } }, "/api/v1/labels/{labelId}/download": { "get": { "operationId": "ShipmentBcLabelOperationsController_getDownloadUrl", "parameters": [ { "name": "labelId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelDownloadResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Etiquetas" ], "summary": "Obter URL de download da etiqueta", "description": "Retorna uma URL temporária para baixar o arquivo da etiqueta.", "security": [ { "bearer": [] } ] } }, "/api/v1/fiscal-documents/shipments/{id}/dace": { "post": { "operationId": "ShipmentFiscalDocumentBcController_generate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateShipmentDaceDto" } } } }, "responses": { "201": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentDaceResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "DACE" ], "summary": "Gerar DACE", "description": "Gera o DACE do envio elegível. A etiqueta deve estar emitida e a DC-e correspondente disponível.", "security": [ { "bearer": [] } ] }, "get": { "operationId": "ShipmentFiscalDocumentBcController_latestDace", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentDaceResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "DACE" ], "summary": "Consultar DACE", "description": "Retorna a disponibilidade e o DACE mais recente do envio.", "security": [ { "bearer": [] } ] } }, "/api/v1/fiscal-documents/shipments/{id}/dace/download": { "get": { "operationId": "ShipmentFiscalDocumentBcController_daceDownload", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentDaceDownloadResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "DACE" ], "summary": "Baixar DACE", "description": "Retorna uma URL temporária ou os dados do DACE térmico mais recente.", "security": [ { "bearer": [] } ] } }, "/api/v1/tracking/code/{trackingCode}": { "get": { "operationId": "ShipmentBcTrackingController_getTrackingByCode", "parameters": [ { "name": "trackingCode", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "refresh", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingEventsResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Rastreamento" ], "summary": "Rastrear por código", "description": "Retorna os eventos do código. Use refresh=true somente quando necessário.", "security": [ { "bearer": [] } ] } }, "/api/v1/tracking/shipments/{id}/tracking-events": { "get": { "operationId": "ShipmentBcTrackingController_getShipmentTrackingEvents", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number, starting at 1", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page", "schema": { "minimum": 1, "default": 10, "type": "number" } }, { "name": "X-Tenant-Id", "in": "header", "required": true, "description": "ID da loja retornado em lojas[].id durante o login.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operação concluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingEventsPageResponse" } } } }, "default": { "description": "Erro no formato padrão da API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Rastreamento" ], "summary": "Listar eventos de um envio", "description": "Retorna o histórico paginado e normalizado de eventos do envio.", "security": [ { "bearer": [] } ] } } }, "components": { "schemas": { "LoginDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "voce@empresa.com.br" }, "senha": { "type": "string", "format": "password", "minLength": 1 } }, "required": [ "email", "senha" ], "additionalProperties": false }, "LoginSessionResponse": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "type": "string", "example": "Bearer" }, "userId": { "type": "string", "format": "uuid" }, "lojas": { "type": "array", "items": { "$ref": "#/components/schemas/UserStoreSummary" } } }, "required": [ "accessToken", "refreshToken", "tokenType", "userId", "lojas" ], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "path": { "type": "string" }, "error": { "type": "string" }, "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "messages": { "type": "array", "items": { "type": "string" } } }, "required": [ "statusCode", "timestamp", "path" ], "additionalProperties": false }, "RefreshTokenDto": { "type": "object", "properties": { "token": { "type": "string", "minLength": 32, "description": "Refresh token mais recente retornado pela API." } }, "required": [ "token" ], "additionalProperties": false }, "RefreshSessionResponse": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "type": "string", "example": "Bearer" }, "userId": { "type": "string", "format": "uuid" } }, "required": [ "accessToken", "refreshToken", "tokenType", "userId" ], "additionalProperties": false }, "AddressManagementListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AddressManagementResponseDto" } }, "total": { "type": "integer", "example": 1 }, "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 20 } }, "required": [ "data", "total", "page", "pageSize" ], "additionalProperties": false }, "AddressManagementBodyDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Matriz São Paulo", "description": "Nome usado para identificar o remetente." }, "personName": { "type": "string", "example": "João Silva", "description": "Pessoa responsável pela postagem." }, "company": { "type": "string", "example": "Loja Exemplo Ltda." }, "phone": { "type": "string", "example": "11999999999" }, "email": { "type": "string", "format": "email", "example": "expedicao@empresa.com.br" }, "street": { "type": "string", "example": "Avenida Paulista" }, "number": { "type": "string", "example": "1000" }, "complement": { "type": "string", "example": "Conjunto 101" }, "district": { "type": "string", "example": "Bela Vista" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "minLength": 2, "maxLength": 2, "example": "SP", "description": "UF com duas letras para endereços no Brasil." }, "zip": { "type": "string", "pattern": "^[0-9]{8}$", "example": "01310100", "description": "CEP com oito dígitos para endereços no Brasil." }, "cpfCnpj": { "type": "string", "pattern": "^([0-9]{11}|[0-9]{14})$", "example": "11222333000181", "description": "CPF ou CNPJ do remetente, somente dígitos." }, "ieNumber": { "type": "string", "example": "110042490114", "description": "Inscrição estadual, quando aplicável." }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "default": "BR", "example": "BR", "description": "Código ISO 3166-1 alfa-2 do país." }, "setAsDefault": { "type": "boolean", "default": false, "description": "Define este remetente como padrão da loja." } }, "required": [ "name", "phone", "street", "number", "district", "city", "state", "zip", "cpfCnpj" ], "additionalProperties": false }, "AddressManagementResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lojaId": { "type": "string", "format": "uuid" }, "addressType": { "type": "string", "enum": [ "SENDER" ] }, "name": { "type": "string" }, "personName": { "type": "string" }, "company": { "type": "string", "nullable": true }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "cpfCnpj": { "type": "string", "nullable": true }, "ieNumber": { "type": "string", "nullable": true }, "country": { "type": "string" }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "lojaId", "addressType", "name", "personName", "phone", "street", "number", "district", "city", "state", "zip", "country", "isDefault", "createdAt", "updatedAt" ], "additionalProperties": false }, "RecipientListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientResponseDto" } }, "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 1 } }, "required": [ "data", "page", "pageSize", "total" ], "additionalProperties": false }, "RecipientCreateDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Maria Oliveira" }, "cpfCnpj": { "type": "string", "pattern": "^([0-9]{11}|[0-9]{14})$", "example": "52998224725", "description": "CPF ou CNPJ, somente dígitos. Obrigatório para destinatário no Brasil." }, "phone": { "type": "string", "pattern": "^[0-9+\\-()\\s]{8,20}$", "example": "21999999999" }, "email": { "type": "string", "format": "email", "example": "maria@example.com" }, "notes": { "type": "string", "example": "Receber na portaria" }, "address": { "$ref": "#/components/schemas/AddressInputDto" } }, "required": [ "name", "phone", "address" ], "additionalProperties": false }, "RecipientResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lojaId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "cpfCnpj": { "type": "string", "nullable": true }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "notes": { "type": "string", "nullable": true }, "addressId": { "type": "string", "format": "uuid" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "address": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/RecipientAddressResponseDto" } ], "nullable": true } }, "required": [ "id", "lojaId", "name", "phone", "addressId", "createdAt", "updatedAt" ], "additionalProperties": false }, "FreightSimulateDto": { "type": "object", "properties": { "shipDate": { "type": "string" }, "originCountryCode": { "type": "string" }, "originPostalCode": { "type": "string" }, "originStateOrProvinceCode": { "type": "string" }, "originCity": { "type": "string" }, "destinationCountryCode": { "type": "string" }, "destinationPostalCode": { "type": "string" }, "destinationStateOrProvinceCode": { "type": "string" }, "destinationCity": { "type": "string" }, "originCep": { "type": "string", "example": "01310100", "description": "CEP de origem. Obrigatório quando originPostalCode não for enviado." }, "destinationCep": { "type": "string", "example": "20040020", "description": "CEP de destino. Obrigatório quando destinationPostalCode não for enviado." }, "peso": { "type": "number", "example": 1.5, "description": "Peso total em quilogramas." }, "comprimento": { "type": "number", "example": 30, "description": "Comprimento em centímetros." }, "largura": { "type": "number", "example": 20, "description": "Largura em centímetros. Obrigatória para envelope e caixa." }, "altura": { "type": "number", "example": 10, "description": "Altura em centímetros. Para caixa, envie altura ou espessura." }, "espessura": { "type": "number", "description": "Alternativa a altura para caixa e opcional para envelope." }, "diametro": { "type": "number", "example": 12, "description": "Diâmetro em centímetros. Obrigatório para cilindro." }, "valorDeclarado": { "type": "number" }, "declaredValueCents": { "type": "number" }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteSimulationPackageDto" } }, "services": { "type": "array", "items": { "type": "string" } }, "serviceLevelId": { "type": "string" }, "carrierId": { "type": "string" }, "carrierSlug": { "type": "string" }, "physicalSpaceId": { "type": "string" }, "additionalServices": { "type": "array", "items": { "type": "string" } }, "dynamicAdditionalServices": { "type": "array", "items": { "type": "object" } }, "format": { "type": "string", "enum": [ "1", "2", "3" ], "default": "2", "description": "Formato: 1 envelope, 2 caixa/pacote e 3 cilindro/rolo." }, "hasPackaging": { "type": "boolean" }, "providerOptions": { "type": "object" } }, "required": [ "peso", "comprimento" ], "allOf": [ { "anyOf": [ { "required": [ "originCep" ] }, { "required": [ "originPostalCode" ] } ] }, { "anyOf": [ { "required": [ "destinationCep" ] }, { "required": [ "destinationPostalCode" ] } ] }, { "oneOf": [ { "properties": { "format": { "enum": [ "1" ] } }, "required": [ "format", "largura" ] }, { "properties": { "format": { "enum": [ "3" ] } }, "required": [ "format", "diametro" ] }, { "properties": { "format": { "enum": [ "2" ] } }, "required": [ "largura" ], "anyOf": [ { "required": [ "altura" ] }, { "required": [ "espessura" ] } ] } ] } ] }, "QuoteSimulationResponse": { "type": "object", "properties": { "shippingOptions": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteSimulationOption" } }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "quotedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "shippingOptions", "quotedAt", "expiresAt" ], "additionalProperties": false }, "FreightSimulateInternationalDto": { "type": "object", "properties": { "shipDate": { "type": "string" }, "originCountryCode": { "type": "string" }, "originPostalCode": { "type": "string" }, "originStateOrProvinceCode": { "type": "string" }, "originCity": { "type": "string" }, "destinationCountryCode": { "type": "string" }, "destinationPostalCode": { "type": "string" }, "destinationStateOrProvinceCode": { "type": "string" }, "destinationCity": { "type": "string" }, "originCep": { "type": "string", "example": "01310100", "description": "CEP de origem. Obrigatório quando originPostalCode não for enviado." }, "destinationCep": { "type": "string", "example": "20040020", "description": "CEP de destino. Obrigatório quando destinationPostalCode não for enviado." }, "peso": { "type": "number", "example": 1.5, "description": "Peso total em quilogramas." }, "comprimento": { "type": "number", "example": 30, "description": "Comprimento em centímetros." }, "largura": { "type": "number", "example": 20, "description": "Largura em centímetros. Obrigatória para envelope e caixa." }, "altura": { "type": "number", "example": 10, "description": "Altura em centímetros. Para caixa, envie altura ou espessura." }, "espessura": { "type": "number", "description": "Alternativa a altura para caixa e opcional para envelope." }, "diametro": { "type": "number", "example": 12, "description": "Diâmetro em centímetros. Obrigatório para cilindro." }, "valorDeclarado": { "type": "number" }, "declaredValueCents": { "type": "number" }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteSimulationPackageDto" } }, "services": { "type": "array", "items": { "type": "string" } }, "serviceLevelId": { "type": "string" }, "carrierId": { "type": "string" }, "carrierSlug": { "type": "string" }, "physicalSpaceId": { "type": "string" }, "additionalServices": { "type": "array", "items": { "type": "string" } }, "dynamicAdditionalServices": { "type": "array", "items": { "type": "object" } }, "format": { "type": "string", "enum": [ "1", "2", "3" ], "default": "2", "description": "Formato: 1 envelope, 2 caixa/pacote e 3 cilindro/rolo." }, "hasPackaging": { "type": "boolean" }, "providerOptions": { "type": "object" } }, "required": [ "peso", "comprimento" ], "allOf": [ { "anyOf": [ { "required": [ "originCep" ] }, { "required": [ "originPostalCode" ] } ] }, { "anyOf": [ { "required": [ "destinationCep" ] }, { "required": [ "destinationPostalCode" ] } ] }, { "oneOf": [ { "properties": { "format": { "enum": [ "1" ] } }, "required": [ "format", "largura" ] }, { "properties": { "format": { "enum": [ "3" ] } }, "required": [ "format", "diametro" ] }, { "properties": { "format": { "enum": [ "2" ] } }, "required": [ "largura" ], "anyOf": [ { "required": [ "altura" ] }, { "required": [ "espessura" ] } ] } ] } ] }, "IntegrationCreateShipmentDto": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid", "description": "Identificador da opção retornada pela cotação." }, "carrierId": { "type": "string", "format": "uuid", "description": "carrierId da mesma opção de cotação." }, "serviceLevelId": { "type": "string", "format": "uuid", "example": "22222222-2222-4222-8222-222222222222", "description": "serviceLevelId da mesma opção de cotação." }, "externalRef": { "type": "string", "example": "PEDIDO-1001" }, "physicalSpaceId": { "type": "string", "format": "uuid" }, "originAddress": { "$ref": "#/components/schemas/IntegrationShipmentAddressDto" }, "destAddress": { "$ref": "#/components/schemas/IntegrationShipmentAddressDto" }, "parcel": { "$ref": "#/components/schemas/IntegrationShipmentParcelDto" }, "invoice": { "$ref": "#/components/schemas/IntegrationShipmentInvoiceDto" } }, "required": [ "quoteId", "carrierId", "serviceLevelId", "originAddress", "destAddress", "parcel" ], "additionalProperties": false }, "IntegrationCreateShipmentResponseDto": { "type": "object", "properties": { "shipment": { "$ref": "#/components/schemas/IntegrationCreatedShipmentDto" }, "shipmentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "created" } }, "required": [ "shipment", "shipmentId", "status" ], "additionalProperties": false }, "EmitLabelDto": { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "wallet" ], "example": "wallet", "description": "Pagamento da emissão com o saldo disponível da loja." }, "pickupRequested": { "type": "boolean" }, "couponCode": { "type": "string" }, "invoice": { "type": "object", "additionalProperties": true } }, "required": [ "paymentMethod" ], "additionalProperties": false }, "EmitLabelReadyResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "READY" ], "example": "READY" }, "shipmentId": { "type": "string", "format": "uuid" }, "labelId": { "type": "string", "format": "uuid" }, "trackingCode": { "type": "string" }, "fileUrl": { "type": "string", "description": "Referência interna. Use o endpoint de download por labelId." }, "priceCents": { "type": "integer" }, "subtotalCents": { "type": "integer" }, "discountCents": { "type": "integer" }, "couponCode": { "type": "string", "nullable": true }, "paymentMethod": { "type": "string" }, "transactionId": { "type": "string" }, "chargeAlreadyCaptured": { "type": "boolean" } }, "required": [ "status", "shipmentId", "labelId", "trackingCode", "fileUrl", "paymentMethod", "transactionId", "chargeAlreadyCaptured" ], "additionalProperties": false }, "PendingLabelResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PENDING" ], "example": "PENDING" }, "shipmentId": { "type": "string", "format": "uuid" }, "providerJobId": { "type": "string" } }, "required": [ "status", "shipmentId", "providerJobId" ], "additionalProperties": false }, "LabelDownloadResponse": { "type": "object", "properties": { "downloadUrl": { "type": "string", "format": "uri" } }, "required": [ "downloadUrl" ], "additionalProperties": false }, "GenerateShipmentDaceDto": { "type": "object", "properties": { "tipoDace": { "type": "string", "enum": [ "T", "R", "C" ], "default": "R", "description": "Térmico, resumido ou completo." } }, "additionalProperties": false }, "ShipmentDaceResponse": { "type": "object", "properties": { "shipmentId": { "type": "string", "format": "uuid" }, "available": { "type": "boolean" }, "generated": { "type": "boolean" }, "fiscalDocumentStatus": { "type": "string" }, "document": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShipmentDaceDocumentResponse" } ], "nullable": true }, "downloadUrl": { "type": "string", "format": "uri", "nullable": true } }, "required": [ "shipmentId", "available", "generated", "document" ], "additionalProperties": false }, "ShipmentDaceDownloadResponse": { "type": "object", "properties": { "shipmentId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "DACE", "DACE_THERMAL" ] }, "downloadUrl": { "type": "string", "format": "uri" }, "fileUrl": { "type": "string" }, "dados": { "type": "string", "nullable": true } }, "required": [ "shipmentId", "type" ], "additionalProperties": false }, "TrackingEventsResponse": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingEventResponse" } }, "TrackingEventsPageResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingEventResponse" } }, "total": { "type": "integer", "example": 1 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "isDelayed": { "type": "boolean" } }, "required": [ "events", "total", "page", "limit", "isDelayed" ], "additionalProperties": false }, "UserStoreSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "nome": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "AddressInputDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Casa", "description": "Nome usado para identificar o endereço." }, "personName": { "type": "string", "example": "Maria Oliveira", "description": "Pessoa que receberá a encomenda." }, "phone": { "type": "string", "pattern": "^[0-9+\\-()\\s]{8,20}$", "example": "21999999999" }, "email": { "type": "string", "format": "email", "example": "maria@example.com" }, "street": { "type": "string", "example": "Rua do Mercado" }, "number": { "type": "string", "example": "45", "description": "Obrigatório para endereços no Brasil." }, "complement": { "type": "string", "example": "Apto 302" }, "district": { "type": "string", "example": "Centro", "description": "Obrigatório para endereços no Brasil." }, "city": { "type": "string", "example": "Rio de Janeiro" }, "state": { "type": "string", "example": "RJ", "description": "UF com duas letras para endereços no Brasil." }, "zip": { "type": "string", "pattern": "^[0-9]{8}$", "example": "20040020", "description": "CEP com oito dígitos para endereços no Brasil." }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "default": "BR", "example": "BR", "description": "Código ISO 3166-1 alfa-2 do país." } }, "required": [ "name", "personName", "phone", "street", "number", "district", "city", "state", "zip", "country" ], "additionalProperties": false }, "RecipientAddressResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "personName": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "street": { "type": "string" }, "number": { "type": "string" }, "complement": { "type": "string", "nullable": true }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } }, "required": [ "id", "name", "personName", "phone", "street", "number", "district", "city", "state", "zip", "country" ], "additionalProperties": false }, "QuoteSimulationPackageDto": { "type": "object", "properties": { "lengthCm": { "type": "number" }, "widthCm": { "type": "number" }, "heightCm": { "type": "number" }, "weightKg": { "type": "number" }, "quantity": { "type": "number" } }, "required": [ "lengthCm", "widthCm", "heightCm", "weightKg", "quantity" ] }, "QuoteSimulationOption": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "carrierId": { "type": "string", "format": "uuid" }, "carrierSlug": { "type": "string", "example": "correios" }, "codigo": { "type": "string", "example": "PAC" }, "serviceLevelId": { "type": "string", "format": "uuid", "example": "22222222-2222-4222-8222-222222222222", "description": "Identificador interno do serviço. Preserve exatamente o valor recebido." }, "serviceCode": { "type": "string", "example": "PAC" }, "nome": { "type": "string", "example": "PAC" }, "preco": { "type": "number", "format": "double", "example": 18.5 }, "currency": { "type": "string", "example": "BRL" }, "prazoEntrega": { "type": "integer", "nullable": true, "example": 5 }, "quotedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "quoteId", "carrierId", "carrierSlug", "serviceLevelId", "preco", "quotedAt", "expiresAt" ], "additionalProperties": false }, "IntegrationShipmentAddressDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Matriz São Paulo" }, "personName": { "type": "string", "example": "João Silva" }, "phone": { "type": "string", "example": "11999999999" }, "email": { "type": "string", "format": "email", "example": "expedicao@empresa.com.br" }, "company": { "type": "string", "example": "Loja Exemplo Ltda." }, "ieNumber": { "type": "string", "example": "110042490114" }, "street": { "type": "string", "example": "Avenida Paulista" }, "number": { "type": "string", "example": "1000" }, "complement": { "type": "string", "example": "Conjunto 101" }, "district": { "type": "string", "example": "Bela Vista" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "example": "SP" }, "zip": { "type": "string", "example": "01310100", "description": "CEP brasileiro ou código postal do país informado." }, "cpfCnpj": { "type": "string", "pattern": "^([0-9]{11}|[0-9]{14})$", "example": "11222333000181", "description": "CPF ou CNPJ, somente dígitos. Obrigatório no Brasil." }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "example": "BR", "description": "Código ISO 3166-1 alfa-2 do país." } }, "required": [ "name", "personName", "phone", "street", "number", "district", "city", "state", "zip", "country" ], "additionalProperties": false }, "IntegrationShipmentParcelDto": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "1", "2", "3" ], "example": "2", "description": "Formato: 1 envelope, 2 caixa/pacote e 3 cilindro/rolo." }, "weightKg": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 1.5 }, "lengthCm": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 30 }, "widthCm": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 20 }, "heightCm": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 10 }, "thicknessCm": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 2 }, "diameterCm": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 12 }, "declaredValueCents": { "type": "integer", "minimum": 0, "example": 8990 }, "productValueCents": { "type": "integer", "minimum": 0, "example": 8990 }, "quantity": { "type": "integer", "minimum": 1, "example": 1 }, "hasPackaging": { "type": "boolean", "default": true }, "contentDescription": { "type": "string", "example": "Vestuário" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationShipmentProductDto" } }, "packages": { "type": "array", "maxItems": 99, "items": { "$ref": "#/components/schemas/IntegrationShipmentPackageGroupDto" } }, "additionalServices": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationShipmentAdditionalServiceDto" } } }, "required": [ "format", "weightKg", "lengthCm" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "format": { "enum": [ "1" ] } }, "required": [ "format", "widthCm" ] }, { "properties": { "format": { "enum": [ "2" ] } }, "required": [ "format", "widthCm" ], "oneOf": [ { "required": [ "heightCm" ] }, { "required": [ "thicknessCm" ] } ] }, { "properties": { "format": { "enum": [ "3" ] } }, "required": [ "format", "diameterCm" ] } ] } ] }, "IntegrationShipmentInvoiceDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "NFE", "DCE" ], "example": "NFE" }, "numero": { "type": "string", "example": "12345" }, "serie": { "type": "string", "example": "1" }, "valor": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 89.9, "description": "Valor do documento em reais." }, "chaveNFe": { "type": "string", "pattern": "^[0-9]{44}$", "example": "35260811222333000181550010000123451000123456" }, "dataEmissao": { "type": "string", "format": "date", "example": "2026-08-05" } }, "required": [ "type" ], "additionalProperties": false }, "IntegrationCreatedShipmentDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "created" } }, "required": [ "id", "status" ], "additionalProperties": false }, "ShipmentDaceDocumentResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "DACE", "DACE_THERMAL" ] }, "provider": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] }, "fileUrl": { "type": "string", "nullable": true }, "payloadMeta": { "type": "object", "additionalProperties": true }, "providerReference": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "provider", "status", "fileUrl", "payloadMeta", "providerReference", "createdAt" ], "additionalProperties": false }, "TrackingEventResponse": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "POSTED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "DELAYED", "RETURNED", "EXCEPTION" ], "example": "IN_TRANSIT" }, "description": { "type": "string" }, "location": { "type": "string", "nullable": true }, "happenedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "description", "location", "happenedAt" ], "additionalProperties": false }, "IntegrationShipmentProductDto": { "type": "object", "properties": { "content": { "type": "string", "example": "Camiseta de algodão" }, "quantity": { "type": "integer", "minimum": 1, "example": 1 }, "valueCents": { "type": "integer", "minimum": 0, "example": 8990, "description": "Valor unitário do produto em centavos." }, "ncm": { "type": "string", "pattern": "^[0-9]{8}$", "example": "61091000" } }, "required": [ "content", "quantity", "valueCents" ], "additionalProperties": false }, "IntegrationShipmentPackageGroupDto": { "type": "object", "properties": { "lengthCm": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 30 }, "widthCm": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 20 }, "heightCm": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 10 }, "weightKg": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 1.5 }, "quantity": { "type": "integer", "minimum": 1, "example": 1 } }, "required": [ "lengthCm", "widthCm", "heightCm", "weightKg", "quantity" ], "additionalProperties": false }, "IntegrationShipmentAdditionalServiceDto": { "type": "object", "properties": { "code": { "type": "string", "example": "AR" }, "description": { "type": "string", "example": "Aviso de recebimento" } }, "required": [ "code" ], "additionalProperties": false } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "accessToken retornado pelo login ou refresh." } } } }