La API JSON/REST de API .  Todas las respuestas de API son JSON (incluyendo los errores), pero son facilmente convertidas a cualquier lenguaje. Usamos códigos de status y respuesta HTTP estándar.

Para facilitar las pruebas, todos los ejemplos usan una cuenta falsa en un entorno de prueba https://staging.core.instantcard.net/api/v2/. Para implementar nuestros APIs en un ambiente de producción, debe usar el camino base

https://core.instantcard.net/api/v2/

En vez de una llave API estándar, usamos un método POST de inicio de sesión/autenticación para conseguir un token de inicio de sesión. Este token es usado en todas las llamadas que siguen. Ya que el token expira, la autenticación se requiere para cada sesión.

Nota de contactos y direcciones:
Aunque están separados en diferentes secciones, con sus propios endpoints, los contactos y las direcciones están diseñados para trabajar en conjunto. Con este fin, los contactos individuales pueden vincularse a direcciones individuales, y viceversa. Si usted desea tratarlos como una sola entidad, puede definir todos los campos a través de los endpoints de DIRECCIONES (que acepta todos los parámetros que definen un contacto).

Es posible que usted desée ver una llamada ejemplo en un lenguaje que no hemos mostrado. En este caso, porfavor contactáctenos y lo agregaremos lo más pronto posible.

Para probar el API por usted mismo sin una cuenta, use estas credenciales:

El API de InstantCard fue diseñado con ciertos flujos de trabajo en mente. Por ejemplo, al crear una tarjeta desarrollamos un sistema dedicado a crear un borrador, obtener vista previa de ese borrador y actualizarlo si requiere modificaciones. Así que, siéntase en libertad de revisar los flujos recomendados a a continuación. Notará que varios de nuestros endpoints no entran en estos ejemplos, y no son requeridos por el cliente típico.

Si hay algún flujo de trabajo que le gustaría ver pero no está enlistado aquí, por favor,  Contáctenos.

Flujo de Autenticación

Su token de autenticación es un parámetro requerido para cualquier llamada subsecuente. 

1. Inicio de Sesión
   • Use el endpoint AUTHENTICATE USER → para obtener su token de autenticación.
2. Perfil de Usuario
   • Use el endpoint FETCH USER PROFILE → para obtener la información de usuario.

Crear una Nueva Tarjeta

La API fue diseñada para crear las tarjetas como borradores, obtener una vista previa del borrador y actualizar el diseño de ser necesario o finalizar.

1. Crear Borrador
   • Use el endpoint CREATE A NEW CARD → para crear su borrador. (Recuerde, esto no finaliza la tarjeta, y no estará disponible para imprimir todavía).
2. Vista Previa
   • Use el endpoint PREVIEW CARD → para revisar el borrador creado (esto es particularmente útil cuando se usa la herramienta de corte de imagen, al verficar que la tarjeta se vea como usted quiere).
3. Si hay algún problema, Actualice Tarjeta, y vuelva a vista previa.
   • Use el endpoint UPDATE CARD → para corregir cualquier error encontrado en la vista previa..
   • Asegúrese de usar PREVIEW CARD → una vez más para verificar que cualquier cambio sea correcto.
4. Si todo se ve bien, Finalice Tarjeta
   • Si todo se ve bien y la información es correcta después de su última Vista Previa, use el endpoint FINALIZE CARD → para finalizar la nueva tarjeta. Una vez finalizada, ésta puede ser agregada al trabajo de impresión.

Proceso de Checkout

De igual forma que la creación de tarjetas, un trabajo de impresión debe de ser finalizado antes de que sus tarjetas sean enviadas a imprenta. Esto permite que los trabajos sean modificados antes de ser finalizados. También facilita el tener un “carrito de compras” al cual el usuario puede seguir agregando tarjetas.

1. Crear Trabajo de Impresión
   • Use el endpoint CREATE A PRINT JOB → para crear su trabajo de impresión. Las tarjetas pueden ser añadidas durante la creación, durante, o ámbos..
2. Agregue Tarjetas al Trabajo de Impresión
   • Use el endpoint ADD CARDS TO A PRINT JOB → para añadir más tarjetas a un trabajo de impresión ya existente.
3. Select how many copies of each card
   • Use el endpoint UPDATE PRINT JOB → para seleccionar cuántas copias de cada tarjeta quiere en el trabajo de impresión.
   Nota: Cada tarjeta en cierto trabajo de impresión tendrá el mismo número de copias. Si usted necesita un número de copias diferente de alguna tarjeta, cree un trabajo de impresión separado para ésta.
4. Seleccione su proveedor de correo
   • Use el endpoint FETCH SHIPPING PROVIDERS → para veruna lista de los proveedores de correo existentes.
   • UPDATE PRINT JOB → con el ID de su proveedor elegido.
5. Seleccione una Dirección de Entrega
   • Use el endpoint FETCH ALL ADDRESSES → para obtener todas las direcciones  de entrega disponibles.
   • Cree una nueva dirección de entrega si la dirección necesaria no está enlistada, usando el endpoint CREATE SHIPPING ADDRESS →.
   • Si necesita usar una dirección por única ocasión (no quiere guardarla para uso futuro), use el endpoint UPDATE PRINT JOB → para agregar una dirección de único uso al trabajo de impresión.
6. Revisa Balance de Cuenta
   • Use el endpoint CHECK BALANCE → para asegurarse de que tiene suficientes fondos para cubrir el trabajo de impresión, antes de enviarlo.
   • Si la cuenta necesita recarga de fondos, use el endpoint ADD FUNDS →.
7. Enviar el Trabajo de Impresión a  Producción
   • Use el endpoint SUBMIT PRINT JOB → para enviar el trabajo de impresión a la imprenta.
   Nota: Las órdenes enviadas antes de las 4PM EST son impresas y enviadas por correo el mismo día, por lo que es importante verificarque los detallessean correctos antes de enviar.

Login

Endpoint: POST /api/v2/authenticate

Antes de tomar cualquier acción relacionada con el API, usted debe iniciar sesión o aunteticar un usuario. Para hacerlo, ingrese el correo electrónico y contraseña que por lo general usa para acceder al sistema InstantCard (https://online.instantcard.net). Si los datos son correcto, se enviará un token. Si los datos son incorrectos, se arrojará un mensaje 401.

El token es un parámetro requerido para cualquier acción o llamada API subsecuente.

El token expira. Por lo tanto, usted necesita ingresar antes de cada sesión para asegurar que está usando un token válido.

Para realizar pruebas, usted puede usar las siguientes credenciales (sólo le solicitará email y contrasela):

email: [email protected]
contraseña: instantcardapi
ID de organización: 20003827 (InstantCard API)

Acción Muestra:

Respuestas de Éxito de Muestra:

Obtenga perfil de usuario auténtico

Endpoint: GET /api/v2/profile/me

Once you have successfully logged in, you may retrieve your stored user information via this endpoint. This may be used to display the logged-in username, etc.

Sample Call:

Error Status Codes

Sample Successful Response:

Create a Card

Endpoint: POST api/v2/organizations/{organization_id}/cards

authorization

card[card_template_id]

card[data]

First you must create the new card based on and existing template. If you do not know the ID for your template, you may retrieve a list of templates using the CARD TEMPLATES ENDPOINT. Additionally, each template will have different variable fields needed for the “data” key value. If you do not know these values, you may retrieve them using the TEMPLATE FIELDS ENDPOINT.

For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode an image to Base64 →

NOTE: The card created via this endpoint will not be ready for printing. It must first be finalized using the FINALIZE CARD endpoint. This way you may PREVIEW CARD and UPDATE CARD if necessary before finalization.

Sample Call:

Error Status Codes

Sample Successful Response:

Preview Card

Endpoint: GET api/v2/organizations/{organization_id}/cards/{id}/preview

authorization

This is used to preview the card you just created (or may be used after the card is finalized). While the card ID is not added as a header key/value, it is required within the endpoint URL. This Card ID number is the same as that returned in the first entry in the JSON object returned when using the CREATE A CARD endpoint.

Note: If you don’t know the card ID for the card you wish to preview, please use the SEARCH FOR A CARD endpoint.

This endpoint returns two Base64  strings representing both the front and the back card images. For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode a Base64 string→

Sample Call:

Error Status Codes

Sample Successful Response:

Update/Edit Card

Endpoint: PATCH api/v2/organizations/{organization_id}/cards/{id}

authorization

card[data]

If there is a problem with the card you just created, you may use this endpoint to make changes before finalization. This may also be used to update finalized card items—for example, if you wish to update the expiry for a given card.

While the card ID is not added as a header key/value, it is required within the endpoint URL. This Card ID number is the same as that returned in the first entry in the JSON object returned when using the CREATE A CARD endpoint.

Note: If you don’t know the card ID for the card you wish to preview, please use the SEARCH FOR A CARD endpoint.

For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode an image to Base64 →

Sample Call:

Error Status Codes

Sample Successful Response:

Finalize Card

Endpoint: PATCH api/v2/organizations/{organization_id}/cards/{id}/finalize

authorization

This is used to finalize a card. All cards must be finalized before they may be added to a print job. While the card ID is not added as a header key/value, it is required within the endpoint URL. This Card ID number is the same as that returned in the first entry in the JSON object returned when using the CREATE A CARD endpoint.

Note: If you don’t know the card ID for the card you wish to preview, please use the SEARCH FOR A CARD endpoint.

This endpoint may return Base64 strings where there are images found on the card. For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode a Base64 string→

Sample Call:

Error Status Codes

Sample Successful Response:

Search for a Card

Endpoint: GET /api/v2/organizations/20003827/cards/search

authorization

term

page_size

page

This endpoint uses a string to search for a card or cards. It returns a JSON array of objects. Each object contains a card’s ID, template ID, organization ID, its data, and when it was last printed/submitted for printing.

All images return the value “image” to reduce the information returned. To preview images, please use the PREVIEW CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Delete a Card

Endpoint: DELETE api/v2/organizations/{organization_id}/cards/{id}

authorization

This endpoint deletes a given card.

If you do not know the ID of the card you wish to delete, use the SEARCH for a CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch All Cards

Endpoint: GET api/v2/organizations/{organization_id}/cards

authorization

page_size

page

This endpoint retrieves every card for a given organization. It returns a JSON array of objects. Each object contains a card’s ID, template ID, organization ID, its data, and when it was last printed/submitted for printing.

All images return the value “image” to reduce the information returned. To preview images, please use the PREVIEW CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Card

Endpoint: GET api/v2/organizations/{organization_id}/cards/{id}

authorization

This enpoint returns a JSON object which contains a card’s ID, template ID, organization ID, its data, and when it was last printed/submitted for printing.

If you do not know the ID of the card you wish to fetch, use the SEARCH for a CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Card Print History

Endpoint: GET api/v2/organizations/{organization_id}/cards/{id}/print_history

authorization

This endpoint gives the print history of a given card. It returns a JSON array of objects. Each object represents one print order and includes both the status and the time it was processed. A status of “0” indicates the card has not yet been printed. A status of “1” indicates the card has been printed and sent.

If you do not know the ID of the card whose history you wish to view, use the SEARCH for a CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Create a Print Job

Endpoint: POST api/v2/organizations/{organization_id}/print_jobs

To order cards, you must create a new print job. You may either elect to use an address on file or a “One off” address. One-off address data is not saved and is used only for the given print job. To send to a new address you want saved or to search for an adress ID which already exists, use the ADDRESSES endpoints.

Once created, a print job may be modified via the UPDATE PRINT JOB endpoint, or you may add cards to it via the ADD CARDS endpoint. (This is why the “print_job[card_ids]” parameter is not required when initially creating a print job.) If you do not know the ID of your desired shipping provider, you may retrieve a list of available shipping providers using the SHIPPING PROVIDERS endpoint.

NOTEs:
• Creating a print job will not automatically send cards to be printed. You must use the SUBMIT PRINT JOB endpoint to finalize an order.
• The print_job[card_ids] parameter should be an array of strings—each string being a card ID number. Even if you are ordering a single card, it must be in the form “[264561]”

Sample Call:

Error Status Codes

Sample Successful Response:

Update a Print Job

Endpoint: PATCH api/v2/organizations/{organization_id}/print_jobs/{id}

To update a print job which was already created, use this endpoint.

Note: patching the print job automatically resets the shipping provider id to “null.” Make sure to resend this value with the patch.

Sample Call:

Error Status Codes

Sample Successful Response:

Add Card(s) to a Print Job

Endpoint: POST api/v2/organizations/{organization_id}/print_jobs/{id}/add_cards

Use this endpoint to add cards to a print job which already exists. If you do not know the print job ID, use the FETCH ALL PRINT JOBS endpoint.

Note: The number of each card printed is inherent to the print job itself. By adding a card to a given job, you will be requesting whatever number of cards is specified within that job. If you need a different amount of a given card, create a new print job.

Sample Call:

Error Status Codes

Sample Successful Response:

Remove a Card from a Print Job

Endpoint: DELETE api/v2/organizations/{organization_id}/print_jobs/{id}/remove_cards/{card_id}

This endpoint will remove an individual card from a print job. To remove multiple cards you must call this endpoint for each card.

Sample Call: