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

# Entrada de Estoque

> https://utilities.mgnsystem.cloud/ag-control/v1/entrada

## **Visão Geral**

Registra movimentações de **entrada de estoque**, integrando dados de NF-e e armazenagem no sistema **MGN SYSTEM - AG CONTROL**.

Essa API é normalmente utilizada por sistemas externos como o **ERP**, que envia os dados da nota fiscal eletrônica e dos itens armazenados para controle logístico.

Método HTTP: POST `/v1/entrada`

## Headers

| Nome          | Valor              |
| :------------ | :----------------- |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

## Campos

### Emitente

| **Nome**               | **Tipo** | **Descrição**                        |
| :--------------------- | :------- | :----------------------------------- |
| `tipo_parceiro`        | string   | `COMPANHIA` / `CLIENTE`              |
| `nome`                 | string   | Nome ou razão social do destinatário |
| `documento`            | string   | CNPJ ou CPF do destinatário          |
| `endereco.logradouro`  | string   | Nome da rua / avenida                |
| `endereco.numero`      | string   | Número do endereço                   |
| `endereco.complemento` | string   | Complemento (opcional)               |
| `endereco.bairro`      | string   | Bairro                               |
| `endereco.cep`         | string   | CEP no formato 00000-000             |
| `endereco.cidade`      | string   | Cidade                               |
| `endereco.uf`          | string   | UF (sigla do estado)                 |
| `endereco.pais`        | string   | País                                 |
| `endereco.latitude`    | string   | Latitude geográfica                  |
| `endereco.longitude`   | string   | Longitude geográfica                 |

### Destinatário

| **Nome**               | **Tipo** | **Descrição**                        |
| :--------------------- | :------- | :----------------------------------- |
| `nome`                 | string   | Nome ou razão social do destinatário |
| `documento`            | string   | CNPJ ou CPF do destinatário          |
| `tipo_parceiro`        | string   | `CLIENTE` /  `ARMAZEM`               |
| `endereco.logradouro`  | string   | Nome da rua / avenida                |
| `endereco.numero`      | string   | Número do endereço                   |
| `endereco.complemento` | string   | Complemento (opcional)               |
| `endereco.bairro`      | string   | Bairro                               |
| `endereco.cep`         | string   | CEP no formato 00000-000             |
| `endereco.cidade`      | string   | Cidade                               |
| `endereco.uf`          | string   | UF (sigla do estado)                 |
| `endereco.pais`        | string   | País                                 |
| `endereco.latitude`    | string   | Latitude geográfica                  |
| `endereco.longitude`   | string   | Longitude geográfica                 |

### Embarque

| **Nome**       | **Tipo**            | **Descrição**                    |
| :------------- | :------------------ | :------------------------------- |
| `nf_entrada`   | string              | Número da Nota Fiscal de Entrada |
| `data_emissao` | string (YYYY-MM-DD) | Data de emissão da nota fiscal   |
| `itens`        | array de objetos    | Lista de itens recebidos         |

### Embarque (array dentro de \*\*`embarque.itens`)

| Nome              | Tipo                | Descrição                         |
| :---------------- | :------------------ | :-------------------------------- |
| `codigo`          | string              | Código do produto                 |
| `descricao`       | string              | Descrição do produto              |
| `unidade`         | string              | Unidade de medida (ex: KG, L, CX) |
| `quantidade`      | number              | Quantidade recebida               |
| `lote`            | string              | Código do lote                    |
| `data_fabricacao` | string (YYYY-MM-DD) | Data de fabricação                |
| `data_vencimento` | string (YYYY-MM-DD) | Data de vencimento                |
| `valor_unitario`  | number              | Valor unitário do produto         |

## **Exemplo**

<RequestExample>
  ```json body theme={null}
  [
      {
        "emitente": {
          "tipo_parceiro": "COMPANHIA",
          "nome": "EMPRESA EMBARCADORA LTDA",
          "documento": "55.444.333/0001-22",
          "endereco": {
            "cep": "80010-000",
            "logradouro": "Av. Central",
            "numero": "500",
            "bairro": "Centro",
            "cidade": "Curitiba",
            "uf": "PR",
            "pais": "Brasil"
          }
        },
        "destinatario": {
          "tipo_parceiro": "ARMAZEM",
          "nome": "AG LOGISTICA SUL",
          "documento": "98.765.432/0001-11",
          "endereco": {
            "cep": "95010-000",
            "logradouro": "Rodovia BR-116",
            "numero": "KM 150",
            "bairro": "Zona Rural",
            "cidade": "Caxias do Sul",
            "uf": "RS",
            "pais": "Brasil",
            "latitude": "-29.167839",
            "longitude": "-51.179385"
          }
        },
        "embarque": {
          "nf_entrada": "NF987654",
          "data_emissao": "2026-02-02",
          "itens": [
            {
              "codigo": "PROD-COMPANHIA-01",
              "descricao": "Produto COMPANHIA",
              "unidade": "UN",
              "quantidade": "200",
              "lote": "CL20260202",
              "data_fabricacao": "2026-01-20",
              "data_vencimento": "2026-06-20",
              "valor_unitario": "5.30"
            }
          ]
        }
      }
    ]
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
  	"status": "ok",
  	"mensagem": "Entradas processadas com sucesso"
  }
  ```
</ResponseExample>

## Erros comuns

| **Código** | **Mensagem**                                        | **Causa Provável**                      |
| :--------- | :-------------------------------------------------- | :-------------------------------------- |
| 400        | Campos obrigatórios ausentes                        | Campo como `nf_entrada` ou `itens` nulo |
| 403        | Usuário sem vínculo com a empresa                   | Token não corresponde à empresa enviada |
| 422        | Documento do destinatário inválido ou mal formatado | CPF/CNPJ incorreto                      |
| 500        | Erro interno ao processar entrada                   | Dados inconsistentes ou duplicados      |

<Note>
  * A movimentação registrada tem tipo\_movimentacao = 'ENTRADA'.
  * Se o produto, armazém ou parceiro ainda não existir, será criado automaticamente vinculado à empresa.
  * A função respeita as **RLS policies** para garantir que o usuário só altere dados da empresa à qual está vinculado.
</Note>