API
É com grande entusiasmo que damos as boas-vindas ao nosso Portal de APIs. Estamos empolgados por você estar aqui e fazer parte do nosso ecossistema de desenvolvedores e parceiros.
Nossa plataforma de APIs foi projetada para simplificar e potencializar a integração das nossas soluções em seus projetos. Queremos que sua experiência seja produtiva e gratificante, permitindo que você aproveite ao máximo os recursos que oferecemos.
O que você pode esperar do nosso Portal de APIs:
| Documentação Abrangente | Nossa documentação detalhada e exemplos práticos irão guiá-lo através dos processos de integração, desde a obtenção de chaves de API até a implementação de chamadas complexas. |
| Acesso Simplificado | Facilitamos o processo de autenticação e acesso às APIs para que você possa começar a experimentar nossos serviços sem obstáculos. |
| Suporte Amigável | Se surgirem dúvidas ou desafios, nossa equipe de suporte está pronta para ajudar. Não hesite em entrar em contato conosco através do e-mail ajuda@omnik.com.br caso precise de assistência. |
| Recursos de Análise | Oferecemos ferramentas para monitorar o uso das APIs, permitindo que você avalie o desempenho e tome decisões informadas. |
| Atualizações Regulares | Mantemos nosso Portal de APIs atualizado com as últimas informações e melhorias para garantir que sua experiência seja sempre aprimorada. |
Lembre-se de que você não está sozinho nessa jornada. Nossa equipe está aqui para apoiar seus esforços e ajudá-lo a atingir seus objetivos de integração.
Métodos HTTP
O protocolo HTTP define um conjunto de métodos de requisição responsáveis por indicar a ação a ser executada para um dado recurso.
| MÉTODO | CRUD | DESCRIÇÃO |
|---|---|---|
| GET | Consulta | Utilizado para obter, recuperar um recurso. |
| POST | Inclusão | Utilizado para criar um novo recurso. |
| PUT | Alteração | Utilizado para aplicar alteração em todas as informações de um determinado recurso. |
| PATCH | Alteração parcial | Utilizado para aplicar alterações parciais em um recurso. |
| DELETE | Exclusão | Utilizado para remover um recurso específico. |
Códigos HTTP
| Código | Motivo |
|---|---|
| 200 | Sucesso, solicitação foi aceita para processamento e concluída. |
| 201 | Sucesso, solicitação foi aceita para processamento e concluída. |
| 202 | Sucesso, porém, a solicitação foi aceita para processamento, mas o processamento não foi concluído, pois não há alterações. |
| 204 | Sucesso, porém, a solicitação foi aceita para processamento, mas o processamento não foi concluído, pois não há alterações. |
| 208 | Já reportado. |
| 400 | Bad Request, inválido ou mal formatado. |
| 401 | Você não tem permissão para acessar essas informações, você não forneceu a autorização necessária para esta operação. |
| 403 | Acesso negado, você não tem permissão para acessar. |
| 404 | Não encontrado. |
| 405 | Método não permitido. |
| 406 | A mídia não é suportada. |
| 405 | Método não permitido. |
| 409 | O servidor entendeu a solicitação, mas se recusa a autorizá-la. |
| 413 | A entidade de solicitação é maior que os limites definidos pelo servidor. |
| 422 | Não processável, erro de negócio ou de validação de dados. |
| 429 | Rate limit, indica que o usuário enviou muitas solicitações em um determinado período de tempo ("limitação de taxa"). |
| 500 | Indica que o servidor encontrou uma condição inesperada que o impediu de atender à solicitação. |
| 503 | O serviço está indisponível. |
| 504 | Gateway timeout |
Autenticação
O que é?
Uma credencial de API (Application Programming Interface) é um conjunto de informações, como chaves de acesso e tokens, que são usadas para autenticar e autorizar o acesso a uma API específica. APIs são conjuntos de regras e protocolos que permitem que diferentes sistemas de software se comuniquem e interajam entre si.
As credenciais de API são utilizadas para verificar a identidade e permissões do solicitante de uma API. Elas garantem que apenas aplicativos, serviços ou usuários autorizados possam acessar os recursos disponibilizados pela API. Geralmente, uma credencial de API é composta por um ou mais elementos, como:
- Chave de API
- Token de Acesso
- Segredo de API
- Identificadores e senhas
- Certificados digitais
*no Portal do Seller, o modelo de credencial adotada é Chave de API
As credenciais de API desempenham um papel fundamental na proteção de recursos sensíveis e na prevenção de acessos não autorizados. Quando você desenvolve ou utiliza um aplicativo que consome uma API, é importante manter suas credenciais de API em segurança, não compartilhá-las publicamente e seguir as melhores práticas de segurança recomendadas pelo provedor da API.
Para que serve?
Uma credencial de API serve para autenticar e autorizar o acesso a uma API (Application Programming Interface). Ela desempenha um papel crucial na segurança e no controle do acesso aos recursos e funcionalidades disponibilizados por uma API. Aqui estão as principais funções de uma credencial de API:
- Autenticação: Uma credencial de API é usada para verificar a identidade do aplicativo, serviço ou usuário que está fazendo uma solicitação à API. Isso ajuda a garantir que apenas entidades autorizadas possam acessar os recursos da API.
- Autorização: Além de autenticar, as credenciais de API também são usadas para determinar quais ações e recursos específicos estão autorizados para o solicitante. Isso permite que o provedor da API controle exatamente o que cada usuário ou aplicativo pode fazer.
- Segurança: As credenciais de API ajudam a proteger os recursos sensíveis da API contra acessos não autorizados. Ao exigir autenticação e autorização, a API pode impedir que pessoas ou aplicativos mal-intencionados acessem ou manipulem informações confidenciais.
- Rastreamento e Monitoramento: Ao usar credenciais de API, é possível rastrear e monitorar o uso da API por parte de diferentes aplicativos ou usuários. Isso fornece informações valiosas sobre a utilização dos recursos e pode ajudar a identificar atividades suspeitas.
- Rate Limiting: As credenciais de API também permitem a implementação de limites de taxa (rate limiting), o que significa que você pode definir quantas solicitações um aplicativo ou usuário específico pode fazer em um determinado período de tempo. Isso evita sobrecarregar a API e mantém um equilíbrio saudável de recursos.
- Geração de Estatísticas: Ao rastrear o uso das credenciais de API, os provedores podem coletar estatísticas sobre quais recursos são mais populares, como os usuários interagem com a API e outras métricas relevantes.
Em resumo, uma credencial de API serve como um mecanismo para garantir a segurança, a privacidade e a conformidade no uso de uma API. Ela permite que o provedor da API tenha controle total sobre quem pode acessar seus recursos e como eles podem ser utilizados.
Onde é usado?
As credenciais de API são usadas em uma variedade de cenários para autenticar e autorizar o acesso a APIs (Application Programming Interfaces). Aqui estão alguns dos principais contextos em que as credenciais de API são empregadas:
- Aplicações Web e Mobile
- Integração de Serviços
- Autenticação de Usuário
- Acesso a Dados e Recursos
- Serviços de Pagamento
- Redes Sociais
- Acesso a Plataformas de Cloud Computing
- IoT (Internet of Things )
- Análise e Monitoramento
*no Portal do Seller, a credencial é usado para autenticar a aplicação WEB
Em resumo, as credenciais de API são usadas sempre que há a necessidade de autenticar, autorizar e controlar o acesso a recursos, dados ou funcionalidades oferecidos por uma API específica. Elas são uma parte fundamental da segurança e da gestão de acesso em sistemas que se comunicam através de APIs.
Como cadastrar uma Credencial?
Na tela de "Manutenção de Credenciais" é possível cadastrar um Token que será usado na API e "amarrar" um Endpoint de Callback para este Token:
Ao selecionar a opção para inclusão de uma nova credencial, sua senha será solicitada:
(POST) Callback
API Endpoint
https://api.seu-dns.com.br/
# Here is a curl example
curl --location 'api.seu-dns.com.br' \
--header 'token: ' \
--header 'Content-Type: application/json' \
--data '{
"account": "string",
"date": "1970-01-01T00:00:00.000000",
"seller": "string",
"operator": "string",
"acronym": "string",
"holding": "string",
"event": "string",
"resourceType": "string",
"resourceId": "{id}",
"resourceURI": "/{contexto}/{id}",
"json": {}
}'
Result example 2xx:
{
}
Result example 4xx:
{
}
Result example 5xx:
{
}
O que é um Callback e para que serve?
Nossa API possuí diversos Endpoint que abrange quase todas as funcionalidades do Seller Center, em muitos desses Endpoints precisamos usar um recurso chamado callback ou notificação de evento.
Esse recurso tem como finalidade notificar o cliente (por meio de um POST) um determinado evento que tenha acontecido no dado dele, por exemplo:
-
Uma alteração de estoque que tenha acontecido dentro da nossa ferramente, vamos fazer um POST na URL do cliente cadastrada, o JSON deste POST irá conter vários campos, dentre eles:
- event: UPDATE
- resourceType: INVENTORY
-
Uma adição na nossa base de um Pedido via integração com parceiro, faremos um POST na URL do cliente cadastrada, o JSON deste POST irá conter vários campos, dentre eles:
- event:
- resourceType: ORDER
- event:
- Autenticação de Usuário
- Acesso a Dados e Recursos
- Serviços de Pagamento
- Redes Sociais
- Acesso a Plataformas de Cloud Computing
- IoT (Internet of Things)
- Análise e Monitoramento
Muito eventos de inclusão, alteração ou exclusão de dados são notificados ao cliente, isso acontece porque, dependendo da atividade e forma com que os clientes usam nossa ferramente, eles precisam sincronizar os dados do lado deles (ou em algum outro lugar), sendo assim, fazemos as notificações e posteriormente (logo em seguida) eles fazem um GET na nossa API para pegar o dado atualizado (em casos como preço, prazo e estoque o JSON do POST será enviado com os dados atualizados).
Como cadastrar um Callback? Veja em “API > Autenticação”.
Header Parameters
| Campo | Tipo | Descrição |
|---|---|---|
| token | string | Authorization do seu Endpoint |
Body Parameters
| Campo | Tipo | Descrição |
|---|---|---|
| account | string | Deprecated |
| date | string | Pattern: yyyy-MM-dd'T'HH:mm:ss.SSS'000 |
| seller | string | Tenant (sem as letras) |
| operator | string | Tenant (sem as letras) |
| acronym | string | Tenant (sem os números) |
| holding | string | |
| event | string | INSERT, UPDATE, NEW, APPROVED, PARTIALLYRETURNED, PARTIALLYCANCELED, SELLER_PAYMENT_PENDING, INVOICED, SENT, DELIVERED, CANCELED, RETIRED, RETURNED, PUBLISHED, NOT_PUBLISHED, SHIPPING_LABEL, MODERATION_APPROVED, MODERATION_NOT_APPROVED, ERROR_ORDER, ERROR_PRODUCT, RECALCULATE_LATE_ORDER, AVAILABLE_CREDIT, ACTIVATED, FINISHED, PAUSED, INVALIDATED, SKU_INSERTED ou SKU_REMOVED |
| resourceType | string | ORDER, PRODUCT, SKU, OFFER, INVENTORY, PRICE, CROSSDOCKING_DAYS, TICKET, SELLER ou CUSTOMER_SERVICE |
| resourceId | string | ID do dado |
| resourceURI | string | URI base para realizar a consulta do dado |
| json | object | Conteúdo incluído/alterado da respectiva notificação |
(GET) Ponto de Controle
API Endpoint
https://api.omnik.io/HUB/v1/controlspoints
# Here is a curl example
curl --location 'https://api.omnik.io/HUB/v1/controlspoints' \
--header 'token: {token}' \
--header 'application_id: {application_id}' \
--header 'seller: {seller-tenant}' \
--header 'resource: {resource}' \
--header 'type: {type}' \
--header 'id: {id}' \
--header 'Content-Type: application/json'
Result example 2xx:
{
"total": 0,
"limit": 0,
"sort": "string",
"values": [
{
"createDate": "1970-01-01T00:00:00.000000",
"controlPointData": {
"date": "1970-01-01T00:00:00.000000",
"eventDate": "1970-01-01T00:00:00.000000",
"type": "string",
"description": "string",
"marketplace": "string",
"platform": "string"
},
"user": {
"code": "string",
"name": "string",
"email": "string",
"login": "string",
"hubSessionId": "string"
}
}
]
}
Result example 4xx:
{
"code": "0",
"type": "string",
"message": "string",
"messages": [
{
"code": "0",
"message": "string"
}
]
}
Result example 5xx:
{
"code": "0",
"type": "string",
"message": "string",
"messages": [
{
"code": "0",
"message": "string"
}
]
}
Os Pontos de Controles são registros que gravamos em qualquer eventos do sistema, usado como log analítico, é o primeiro recurso usado pelo Usuário para saber mais sobre eventos o histórico do dado, com esse Endpoint é possível saber por exemplo:
- Quem alterou um Produto
- Quando foi alterado o Preço
- De onde veio a atualização de status do Pedido
- Para qual valor foi alterado o Estoque
- etc
Veja abaixo o funcionamento completo da nossa consulta de Pontos de Controles:
Header Parameters
| Campo | Tipo | Descrição |
|---|---|---|
| token | string | (required) seu token de acesso |
| application_id | string | (required) ID do seu token de acesso |
| seller | string | (optional) Tenant ID do Seller (se Operador) |
| resource | string | (required) SKU, SKU_CATALOG, OFFER, PRODUCT, PRODUCT_CATALOG, BRAND, CATEGORY, VARIANT, INVOICE, ORDER, USER, SELLER ou HUB |
| type | string | (optional) tipo de Ponto de Controle, obrigatório quando o recurso for igual à SKU or OFFER' 'pattern: INVENTORY, PRICE ou CROSSDOCKING_DAYS |
| id | string | (optional) ID do dado, obrigatório quando o recurso for igual à SKU, SKU_CATALOG, OFFER, PRODUCT, PRODUCT_CATALOG, BRAND, CATEGORY, VARIANT, INVOICE, ORDER ou USER |
Query Parameters
| Campo | Tipo | Descrição |
|---|---|---|
| offset | integer | (optional) indica a partir de onde ocorre um aumento |
| limit | integer | (optional) Indica a quantidade de recursos a serem devolvidos, variando de 10 a no máximo 10 |
| sort | string | (optional) Indica por qual atributo a consulta deve ser classificada (lastUpdate ou createDate) (Default lastUpdate) |
| last_update | string($yyyy-MM-dd'T'HH:mm:ss) | (optional) last update |