API de Sellout

Criada por Adrier Santos, Modificado em Ter, 28 Mai, 2024 na (o) 10:43 PM por Adrier Santos

API Sellout

Autenticação
Recomendações
Envio de Vendas
Envio de Clientes
Envio de Estoque

Autenticação

Saiba mais sobre a autenticação em Documentação API Autenticação

Recomendações

Enviar até 500 registros por requisição ou 10mb (enviar a maior quantidade possível de uma única vez)
Limitar o número de envios simultâneos em até 5 threads

Envio de Vendas

As vendas, são todos os tickets (pedidos) gerados, sejam eles concluídos com sucesso ou cancelados.

POST <https://sellout.newtail.com.br/v1/sales/**{store_id}**/**{pos_id}**>

Path Parameters

store_id: Código da loja onde a venda foi realizada
pos_id: Código do PDV onde a venda foi realizada (se não existir o pos_id, enviar 0)

Body

Atributo	Descrição	Tipo	Obrig.	Padrão	Recomendado
invoice_id	Identificador único da venda	String	Sim
currency	Identifica em qual moeda a venda foi paga	String	Não	BRL
total_price	Identifica o total da venda	Float	Sim
sub_total	Identifica o total dos itens da venda sem desconto	Float	Sim
additional_cost	Identifica o total de acréscimo na venda	Float	Não	0
total_discount	Identifica o total de desconto da venda	Float	Não	0
shipping_cost	Identifica o total da entrega na venda	Float	Não
channel	Identifica o canal de origem da venda. Exemplos: - ifood - rappi - local - whatsapp - commerce	String	Sim
status	Identifica o status da nota fiscal. - issued: para venda feita com sucesso - cancelled: para venda cancelada	String	Sim
delivery_type	Diz qual é o tipo de entrega do pedido. - delivery: para entrega - pick_up: retirada	String	Sim
purchase_type	Diz qual foi o tipo de compra. - online: para compras feitas online - local: para compras feitas no local	String	Sim
created_at	Data de criação da venda	String	Sim
customer	Informações do Cliente Final	Object	Não
customer.id	Identificação única do cliente	String	Não
customer.name	Nome do Cliente Final	String	Não
customer.gender	Identifica o gênero do cliente	String	Não
customer.date_of_birth	Identifica a data de nascimento do cliente	String	Não
customer.document	Identifica unicamente o cliente final com o código do registro. ex.: CPF ou CNPJ.	String	Não
Items	Lista de Itens que foram vendidos naquele pedido	Array<Object>	Sim
items[].sku	Identifica unicamente o Produto com um código interno	String	Sim
items[].parent_sku	Identifica unicamente o Produto Pai com um código interno	String	Não	null
items[].original_sku	Identifica o produto substituído (caso houver)	String	Não
items[].unit_measurement	Indica como o produto foi vendido. - KG para venda por kilo - UN para venda por unidade	String	Sim
items[].name	Indica qual é o nome do produto	String
items[].gtins	Indica a lista de Código de Barras do produto	Array<String>	Sim
items[].total_value	Indica qual foi o valor total vendido do produto. (Quantidade * Preço Unitário) - Discount.	Float
items[].unit_price	Indica qual o Preço por Unidade do Produto	Float
items[].quantity	Indica a quantidade vendida do produto	Float
items[].discount	Indica a valor de desconto dado ao produto	Float
items[].brand	Indica qual é o nome da marca do item vendido	String	Não		Sim
items[].categories	Indica quais são as categorias do item vendido	Array<String>	Sim	[]
payments[].type	Identifica qual o tipo de pagamento utilizado. * cash * credit_card * debit_card * other	String	Sim
payments[].total	Identifica o total do pagamento	Float	Sim
payments[].card_first_numbers	Identifica o bin do cartão	String	Não
payments[].card_last_numbers	Identifica os últimos dígitos do cartão	String	Não
payments[].autorization_id	Identifica o código de autorização da transação	String	Não
billing_address	Informações do endereço de cobrança	Object	Não
billing_address.street	Identifica a rua	String	Sim
billing_address.reference	Identifica uma possível referência do endereço	String	Não
billing_address.number	Identifica o número	String	Sim
billing_address.neighborhood	Identifica o bairro	String	Sim
billing_address.city	Identifica a cidade	String	Sim
billing_address.region	Identifica a UF	String	Sim
billing_address.country	Identifica o país	String	Não
billing_address.complement	Identifica o complemento	String	Não
billing_address.full_name	Nome do pagador	String	Não
billing_address.document	Documento (RG ou CPF) do responsável pela cobrança	String	Não
shipping_address	Informações do endereço de entrega	Object	Não
shipping_address.street	Identifica a rua	String	Sim
shipping_address.reference	Identifica uma possível referência do endereço	String	Não
shipping_address.number	Identifica o número	String	Sim
shipping_address.neighborhood	Identifica o bairro	String	Sim
shipping_address.postcode	Código postal	String	Não
shipping_address.city	Identifica a cidade	String	Sim
shipping_address.region	Identifica a UF	String	Sim
shipping_address.country	Identifica o país	String	Não
shipping_address.complement	Identifica o complemento	String	Não
shipping_address.full_name	Nome de quem recebeu o pedido	String	Não
shipping_address.main_phone	Telefone de quem recebeu o pedido	String	Não
shipping_address.document	Documento (RG ou CPF) de quem recebeu o pedido	String	Não

[
    {
        "invoice_id": "53478534",
        "currency": "BRL",
        "total_discount": 2.60,
        "additional_cost": 0.00,
        "total_price": 48.55,
        "shipping_cost": 10.0,
        "sub_total": 38.55,
        "channel": "whatsapp",
        "status": "issued",
        "created_at": "2019-09-13T15:30:25.000-0300",
        "customer": {
            "id": "123",
            "name": "João Silva",
            "document": "62167733305",
            "gender": "male",
            "date_of_birth": "2000-01-01"
        },
        "items": [
            {
                "sku": "01",
                "gtins": [
                    "123"
                ],
                "name": "banana prata",
                "quantity": 3.5,
                "unit_price": 9.70,
                "total_value": 31.35,
                "discount": 2.60,
                "unit_measurement": "kg",
            },
            {
                "sku": "02",
                "gtins": [
                    "7896008100216"
                ],
                "name": "coca cola",
                "quantity": 2.00,
                "unit_price": 3.60,
                "total_value": 7.20,
                "unit_measurement": "un",
            }
        ],
        "shipments": [
            {
                "delivery_type": "delivery",
                "carrier_id": "123",
                "items": [
                    "01",
                    "02"
                ],
                "schedule_date": "2022-02-07",
                "schedule_time_start_at": "14:00",
                "schedule_time_finish_at": "15:00"
            }
        ],
        "payments": [
            {
                "type": "cash",
                "total": 48.55,
                "card_first_numbers": "123456",
                "card_last_numbers": "4776",
                "autorization_id": "123"
            }
        ],
        "billing_address": {
            "street": "Avenida Teste",
            "reference": null,
            "number": "1000",
            "neighborhood": "Bairro",
            "postcode": "22790707",
            "city": "Rio de Janeiro",
            "region": "RJ",
            "country": "Brasil",
            "complement": "Casa 2",
            "full_name": "Joao Souza",
            "main_phone": null,
            "document": "12345678910"
        },
        "shipping_address": {
            "street": "Avenida Teste",
            "reference": null,
            "number": "1000",
            "neighborhood": "Bairro",
            "postcode": "22790707",
            "city": "Rio de Janeiro",
            "region": "RJ",
            "country": "Brasil",
            "complement": "Casa 2",
            "full_name": "Joao Souza",
            "main_phone": null,
            "document": "12345678910"
        }
    }
]

Envio de Clientes

Envio de informações demográficas dos clientes.

POST <https://sellout.newtail.com.br/v1/customers>

Atributo	Descrição	Tipo	Obrigatório
customer_id	Indica qual o identificador único do cliente final	String	Sim
gender	Indica qual o sexo do cliente	String
Valores: F ou M	Não	null
birth_date	data de nascimento	String.
Formato: YYYY-MM-DD	Não	null
state	Unidade federativa (estado)	String
ex.: RJ, SP…	Não	null
city	Cidade do Estado	String
Ex.: Rio de janeiro, São Paulo, …	Não	null
district	Bairro	String
Ex.: Copacabana, Madureira, …	Não	null
postal_code	Cep	String
Ex.: 21000000	Não	null
exists_phone	Indica se o cliente tem telefone de contato cadastrado	Boolean
true ou false	Não	null
exists_email	Indica se o cliente tem email de contato cadastrado	Boolean
true ou false	Não	null

{
    "customer_id": "123",
    "gender": "F",
    "birth_date": "2022-01-01",
    "state": "RJ",
    "city": "Rio de Janeiro",
    "district": "Copacabana",
    "postal_code": "21660000",
    "exists_phone": true,
    "exists_email": false
}

Envio de Estoque

POST <https://sellout.newtail.com.br/v1/stocks/{store_id}>

Path Parameters

store_id: Código da loja onde a venda foi realizada

Atributo	Descrição	Tipo	Obrigatório
sku	Identifica unicamente o Produto com um código interno	String
ex.: abc123	Sim
stock	Quantidade de estoque do produto	Float
ex.: 1.5	Sim
is_dc	indica se este stock é referente a um centro de distribuição	Boolean
true ou false	Não	false
unit_measurement	Indica se o estoque é vendido por KG ou por UN	String
ex.: UN	KG	Não	UN
created_at	Indica qual a datahora que estoque foi gerado	String
Formato: iso8601
Ex.: 2019-09-13T15:30:25.000-03:00	Sim

Respostas com Sucesso

O retorno da requisição terá código HTTP 202 com o seguinte body quando os dados forem enviados com sucesso:

{
    "messages": [
        "sales will be processed soon"
    ]
}

Erros de Validação

Implementamos o padrão https://datatracker.ietf.org/doc/rfc8927/ nas mensagens de erro:

Em caso de erro de validação será enviado um HTTP 422 com os problemas.

{
    "messages": [
        {
            "keyword": "required",
            "params": {
                "missingProperty": "invoice_id"
            },
            "message": "must have required property 'invoice_id'"
        }
    ]
}

Erros Internos

Em caso de erro será enviado um HTTP 5XX com o possível problema.

{
    "messages": [
        "error message"
    ]
}