> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adicionar um documento

Declara um documento adicional para uma entidade existente: um comprovante de endereço, contrato social, procuração ou qualquer outro documento de suporte. Os arquivos são enviados depois com Upload a Proof.

* O documento principal é sempre o documento enviado na criação da entidade. Enviar isPrimary: true aqui retorna 400 VALIDATION\_ERROR.
* A entidade não pode estar IN\_REVIEW, REJECTED, BLOCKED ou CLOSED.

Os erros usam `application/problem+json` com um `code` estável. Catálogo completo: [Entity Statuses and Error Codes](https://docs.localpayment.com/pt-br/reference/entity-statuses-and-error-codes.md).


## OpenAPI

````yaml openapi/pt-br/localpayment.json POST /api/entity/v1/entities/{entityId}/documents
openapi: 3.1.0
info:
  version: '1.0'
  title: Localpayment
  contact:
    name: Support
    url: mailto:support@localpayment.com
servers:
  - url: https://api.stage.localpayment.com
    description: Stage
security:
  - token: []
paths:
  /api/entity/v1/entities/{entityId}/documents:
    post:
      summary: Adicionar um documento
      operationId: add-entity-document
      parameters:
        - name: Authorization
          in: header
          description: >-
            Token de acesso Bearer para autenticação. Este token é obtido nos
            endpoints [Obter token de acesso](/pt-br/reference/get-token) ou
            [Renovar token de acesso](/pt-br/reference/refresh-token). Sua conta
            de comerciante e o usuário que realiza a ação são identificados a
            partir dele.
          required: true
          schema:
            type: string
            examples:
              - Bearer <your_access_token>
        - name: X-Correlation-ID
          in: header
          description: >-
            Identificador de rastreamento (UUID). Exibido na resposta; gerado
            pelo Localpayment se ausente.
          required: false
          schema:
            type: string
            examples:
              - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
        - name: entityId
          in: path
          description: ID interno da entidade.
          required: true
          schema:
            type: string
            examples:
              - 5aced5da-40c1-4bec-85ff-c8cd1bcb4526
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: Consulte Tipos de Documentos e Provas.
                  enum:
                    - DNI
                    - NATIONAL_ID
                    - DRIVER_LICENSE
                    - PASSPORT
                    - CE
                    - CC
                    - CUIT
                    - CUIL
                    - RFC
                    - CURP
                    - CPF
                    - CNPJ
                    - RUC
                    - NIT
                    - TAX_ID
                    - ARTICLES_OF_INCORPORATION
                    - POWER_OF_ATTORNEY
                    - TAX_CERTIFICATE
                    - PAYSLIP
                    - ARCA_REGISTRATION
                    - PROOF_OF_ADDRESS
                    - PROOF_OF_FUNDS
                    - OTHER
                  examples:
                    - PROOF_OF_ADDRESS
                id:
                  type: string
                  description: >-
                    Número do documento, de 1 a 30 caracteres. Único em conjunto
                    com o tipo no seu merchant. Para comprovantes sem número
                    oficial, use sua própria referência (por exemplo, POA-0001).
                  examples:
                    - POA-0001
                issuingCountry:
                  type: string
                  description: ISO 3166-1 alfa-3.
                  examples:
                    - BRA
                issueDate:
                  type: string
                  format: date
                  description: AAAA-MM-DD.
                  examples:
                    - '2024-01-15'
                expirationDate:
                  type: string
                  format: date
                  description: AAAA-MM-DD.
                  examples:
                    - '2034-01-15'
                metadata:
                  type: object
                  description: Metadados de formato livre.
              required:
                - type
                - id
            examples:
              Example 1:
                value:
                  type: PROOF_OF_ADDRESS
                  id: POA-0001
                  issuingCountry: BRA
      responses:
        '201':
          description: Criado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  documentId:
                    type: string
                    examples:
                      - e0ea9515-442e-4bc5-bc82-b8d278255c37
                    format: uuid
                    description: >-
                      Identificador do documento (docId). Use-o para carregar e
                      listar comprovantes.
                  entityId:
                    type: string
                    examples:
                      - 5aced5da-40c1-4bec-85ff-c8cd1bcb4526
                    format: uuid
                    description: Entidade proprietária.
                  type:
                    type: string
                    examples:
                      - PROOF_OF_ADDRESS
                    enum:
                      - DNI
                      - NATIONAL_ID
                      - DRIVER_LICENSE
                      - PASSPORT
                      - CE
                      - CC
                      - CUIT
                      - CUIL
                      - RFC
                      - CURP
                      - CPF
                      - CNPJ
                      - RUC
                      - NIT
                      - TAX_ID
                      - ARTICLES_OF_INCORPORATION
                      - POWER_OF_ATTORNEY
                      - TAX_CERTIFICATE
                      - PAYSLIP
                      - ARCA_REGISTRATION
                      - PROOF_OF_ADDRESS
                      - PROOF_OF_FUNDS
                      - OTHER
                    description: Tipo de documento.
                  id:
                    type: string
                    examples:
                      - POA-0001
                    description: Número do documento conforme declarado.
                  issuingCountry:
                    type: string
                    examples:
                      - BRA
                    description: Emitindo dados conforme declarado.
                  issueDate:
                    type:
                      - string
                      - 'null'
                    format: date
                    description: Emitindo dados conforme declarado.
                  expirationDate:
                    type:
                      - string
                      - 'null'
                    format: date
                    description: Emitindo dados conforme declarado.
                  isPrimary:
                    type: boolean
                    examples:
                      - false
                    description: Documento de identificação da entidade.
                  status:
                    type: string
                    examples:
                      - PENDING
                    enum:
                      - PENDING
                      - VERIFIED
                      - REJECTED
                      - EXPIRED
                    description: >-
                      Status derivado do documento: EXPIRED se a expirationDate
                      tiver passado, REJECTED se alguma prova ativa for
                      rejeitada, VERIFIED se todas as provas ativas forem
                      aprovadas, caso contrário PENDING.
                  metadata:
                    type:
                      - object
                      - 'null'
                    description: Metadados de formato livre.
                  proofs:
                    type: array
                    items:
                      type: object
                    description: >-
                      Comprovantes ativos do documento (os arquivos substituídos
                      não são listados).
                  createdAt:
                    type: string
                    examples:
                      - '2024-01-15T17:03:11Z'
                    format: date-time
                  updatedAt:
                    type: string
                    examples:
                      - '2024-01-15T17:03:11Z'
                    format: date-time
              examples:
                Example 1:
                  value:
                    documentId: e0ea9515-442e-4bc5-bc82-b8d278255c37
                    entityId: 5aced5da-40c1-4bec-85ff-c8cd1bcb4526
                    type: PROOF_OF_ADDRESS
                    id: POA-0001
                    issuingCountry: BRA
                    issueDate: null
                    expirationDate: null
                    isPrimary: false
                    status: PENDING
                    metadata: null
                    proofs: []
                    createdAt: '2024-01-15T17:03:11Z'
                    updatedAt: '2024-01-15T17:03:11Z'
        '400':
          description: >-
            Solicitação inválida. VALIDATION_ERROR: Um campo, cabeçalho, caminho
            ou parâmetro de consulta está ausente, é desconhecido ou inválido.
            details[] lista o campo e o problema.
          content:
            application/problem+json:
              schema:
                type: object
                description: >-
                  Detalhes do problema segundo a RFC 9457
                  (application/problem+json).
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: Breve resumo do problema.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  detail:
                    type: string
                    description: Explicação em linguagem acessível a humanos.
                  instance:
                    type: string
                    description: Caminho da solicitação.
                  code:
                    type: string
                    description: >-
                      Código de erro estável e legível por máquina. Faça a
                      ramificação da lógica com base nesse valor.
                  correlationId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador da solicitação. Informe-o ao entrar em
                      contato com o suporte.
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: Campos problemáticos, quando aplicável.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - VALIDATION_ERROR:
                  value:
                    type: about:blank
                    title: Validation error
                    status: 400
                    detail: >-
                      A field, header, path or query parameter is missing,
                      unknown or invalid. details[] lists field and issue.
                    instance: >-
                      /api/entity/v1/entities/5aced5da-40c1-4bec-85ff-c8cd1bcb4526/documents
                    code: VALIDATION_ERROR
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details:
                      - field: externalId
                        issue: REQUIRED
        '401':
          description: 'Não autorizado. UNAUTHORIZED: Token de acesso ausente ou inválido.'
          content:
            application/problem+json:
              schema:
                type: object
                description: >-
                  Detalhes do problema segundo a RFC 9457
                  (application/problem+json).
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: Breve resumo do problema.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  detail:
                    type: string
                    description: Explicação em linguagem acessível a humanos.
                  instance:
                    type: string
                    description: Caminho da solicitação.
                  code:
                    type: string
                    description: >-
                      Código de erro estável e legível por máquina. Faça a
                      ramificação da lógica com base nesse valor.
                  correlationId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador da solicitação. Informe-o ao entrar em
                      contato com o suporte.
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: Campos problemáticos, quando aplicável.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - UNAUTHORIZED:
                  value:
                    type: about:blank
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid access token.
                    instance: >-
                      /api/entity/v1/entities/5aced5da-40c1-4bec-85ff-c8cd1bcb4526/documents
                    code: UNAUTHORIZED
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
        '404':
          description: >-
            Não encontrado. ENTITY_NOT_FOUND: A entidade não existe ou pertence
            a outro comerciante.
          content:
            application/problem+json:
              schema:
                type: object
                description: >-
                  Detalhes do problema segundo a RFC 9457
                  (application/problem+json).
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: Breve resumo do problema.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  detail:
                    type: string
                    description: Explicação em linguagem acessível a humanos.
                  instance:
                    type: string
                    description: Caminho da solicitação.
                  code:
                    type: string
                    description: >-
                      Código de erro estável e legível por máquina. Faça a
                      ramificação da lógica com base nesse valor.
                  correlationId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador da solicitação. Informe-o ao entrar em
                      contato com o suporte.
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: Campos problemáticos, quando aplicável.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - ENTITY_NOT_FOUND:
                  value:
                    type: about:blank
                    title: Not found
                    status: 404
                    detail: The entity does not exist or belongs to another merchant.
                    instance: >-
                      /api/entity/v1/entities/5aced5da-40c1-4bec-85ff-c8cd1bcb4526/documents
                    code: ENTITY_NOT_FOUND
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
        '409':
          description: >-
            Conflito. DUPLICATE_ENTITY: o externalId, ou o par type + id de um
            documento, já existe em seu cadastro de comerciante.
            ENTITY_NOT_EDITABLE: A entidade está REJECTED, BLOCKED ou CLOSED, ou
            a operação removeria o documento principal ou o único documento.
            ENTITY_IN_REVIEW: A entidade está IN_REVIEW: seus dados, documentos,
            arquivos e vínculos de UBO estão congelados até que o Compliance da
            Localpayment a resolva.
          content:
            application/problem+json:
              schema:
                type: object
                description: >-
                  Detalhes do problema segundo a RFC 9457
                  (application/problem+json).
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: Breve resumo do problema.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  detail:
                    type: string
                    description: Explicação em linguagem acessível a humanos.
                  instance:
                    type: string
                    description: Caminho da solicitação.
                  code:
                    type: string
                    description: >-
                      Código de erro estável e legível por máquina. Faça a
                      ramificação da lógica com base nesse valor.
                  correlationId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador da solicitação. Informe-o ao entrar em
                      contato com o suporte.
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: Campos problemáticos, quando aplicável.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - DUPLICATE_ENTITY:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: >-
                      externalId, or the pair type + id of a document, already
                      exists in your merchant.
                    instance: >-
                      /api/entity/v1/entities/5aced5da-40c1-4bec-85ff-c8cd1bcb4526/documents
                    code: DUPLICATE_ENTITY
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 2 - ENTITY_NOT_EDITABLE:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: >-
                      The entity is REJECTED, BLOCKED or CLOSED, or the
                      operation would remove the primary document or the only
                      document.
                    instance: >-
                      /api/entity/v1/entities/5aced5da-40c1-4bec-85ff-c8cd1bcb4526/documents
                    code: ENTITY_NOT_EDITABLE
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 3 - ENTITY_IN_REVIEW:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: >-
                      The entity is IN_REVIEW: its data, documents, files and
                      UBO links are frozen until Localpayment Compliance
                      resolves it.
                    instance: >-
                      /api/entity/v1/entities/5aced5da-40c1-4bec-85ff-c8cd1bcb4526/documents
                    code: ENTITY_IN_REVIEW
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
      security:
        - token: []
components:
  securitySchemes:
    token:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.